@mfxhub/sdk 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+Every release of `@mfxhub/sdk`, newest first. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## Unreleased
+
+## 0.1.0
+
+The first release. It passes all 72 cases of the shared SDK test suite 0.2.0.
+
+- The foundation: request signing (Ed25519, the published test vector), the client core with
+  rate-limited reads retried and writes never retried, and a typed error for every error code.
+- The shared SDK test suite 0.2.0 runs against this SDK on every change.
+- `client.terminals`: `get`, `page`, `list` (follows the cursor; there is no total) and `create`
+  (an idempotency key is required, and a write is never retried); `isUsable`; the `Page` type.
+- `client.execution.placeOrder`: resolves to an `ExecutionResult` for every outcome and never
+  rejects for what the platform or the network does. A connection that drops after the order was
+  sent reads `UNKNOWN`, not retryable; a timeout is never retryable. Prices and volumes are decimal
+  strings, written as plain digits (`1E+3` is sent as `"1000"`); a number is refused.
+- `client.catalog.quote`: one symbol's quote with its age; prices are the API's decimal strings.
+- `client.stream()`: one signed WebSocket for every channel. `Channel` builds the keys from
+  ids. After a 4008 or 4009 close it reconnects and resumes events, results, account and expert
+  channels from the last `seq`; ticks and candles are subscribed again. 4001 stops with an
+  `AuthError`. A resync and a refused channel arrive as events, not errors, and gaps are counted
+  in `stats`. The socket pauses while frames wait, so a slow reader meets real backpressure.
+- Reads and stream reconnects share one jittered backoff (`backoffMs`).
+- All 72 cases of the shared SDK test suite 0.2.0 pass.
+- CONTRIBUTING.md: how to set up, test, sign off and propose a change.

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# MFX Hub TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The typed TypeScript client for the [MFX Hub](https://mfxhub.com) API: hosted trading terminals for
+your own broker accounts, with market data, execution and a live event stream behind one signed REST
+and WebSocket API.
+
+```bash
+npm install @mfxhub/sdk
+```
+
+Node.js 22 or later, ESM. Every release passes the same shared test suite as the Python SDK.
+
+## First calls
+
+You need an API key: its id, and the private key shown once when it was issued. Keep the private
+key out of your code; the SDK never prints it.
+
+```ts
+import { Channel, MfxClient, StreamMessage, isUsable } from "@mfxhub/sdk";
+
+const client = new MfxClient(
+  "https://api.dev.mfxhub.com/v1", // https://api.mfxhub.com/v1 for production
+  process.env.MFX_KEY_ID!,
+  process.env.MFX_PRIVATE_KEY!, // PEM, or the base64 of the 32-byte key
+);
+
+// Your terminals, following the cursor: there is no total.
+for await (const terminal of client.terminals.list()) {
+  console.log(terminal.id, terminal.state, isUsable(terminal));
+}
+
+// A quote always says how old it is. Prices are decimal strings, every digit kept.
+const quote = await client.catalog.quote(brokerId, "EURUSD");
+console.log(quote.bid, quote.ask, quote.age_s);
+
+// Placing an order never throws for anything the platform or the network does: read the result.
+const result = await client.execution.placeOrder(terminalId, {
+  symbol: "EURUSD",
+  side: "buy",
+  volume: "0.01", // a decimal string; a number is refused
+  idempotencyKey: `order-${Date.now()}`, // the same key again returns the same order, never a second
+});
+if (!result.ok && result.state === "UNKNOWN") {
+  // The order may have reached the broker. Never send it again under a new key.
+}
+
+// One WebSocket for every channel, resumed after a reconnect.
+const stream = await client.stream();
+await stream.subscribe(Channel.results(terminalId));
+for await (const event of stream) {
+  if (event instanceof StreamMessage) console.log(event.channel, event.seq, event.type);
+}
+```
+
+Use a **demo** account while you try it: an order is real on whatever account the terminal is
+logged in to.
+
+## What 0.1.0 covers
+
+| Area      | In this release                                                                       |
+| --------- | ------------------------------------------------------------------------------------- |
+| Signing   | every request and the stream's upgrade, Ed25519                                       |
+| Errors    | one typed error per error code the API names                                          |
+| Terminals | `get`, `page`, `list`, `create`                                                       |
+| Execution | `placeOrder`, with `ExecutionResult` for every outcome                                |
+| Catalogue | `quote`                                                                               |
+| Stream    | `client.stream()`: events, results, account, ticks, candles, book and expert channels |
+
+Submitting a terminal's login, farms, account reads, market-data subscriptions and the rest of
+order management are next. Until then the [Python SDK](https://github.com/mfx-platform/mfx-sdk-python)
+and the API itself cover them. The full API is described at [docs.mfxhub.com](https://docs.mfxhub.com).
+
+## Three rules the SDK keeps
+
+- **Every write takes an idempotency key**, and the SDK never invents one.
+- **Execution never throws** for what the platform or the network does. A connection that dropped
+  after the order was sent reads `UNKNOWN` and `retryable: false`.
+- **Prices, volumes and money are decimal strings.** A JavaScript number is refused before anything
+  is sent, because `0.07 * 3` is `0.21000000000000002`.
+
+## Developing
+
+```bash
+npm ci
+npm test            # vitest, 100% coverage required
+npm run lint && npm run format && npm run typecheck
+npm run gen         # after spec/openapi.yaml changes; CI fails when the generated types drift
+```
+
+### The shared SDK test suite
+
+Every MFX Hub SDK passes the same cases: a fake MFX Hub plays each one back and judges what the SDK
+sent. The suite is vendored in `test/conformance/suite` at the version in
+`test/conformance/suite-version.txt`; its fake hub is a Python 3.12 program.
+
+```bash
+uv venv --python 3.12 .hub
+uv pip install --python .hub --require-hashes -r test/conformance/hub-requirements.txt
+MFX_SUITE_PYTHON=.hub/bin/python npm run test:conformance   # .hub\Scripts\python.exe on Windows
+```
+
+A case this SDK does not pass yet is listed in `test/conformance/not-yet.json` with the reason, and
+must fail until it is removed. To move to a new suite release:
+`node tools/update-suite.mjs <checkout of mfx-sdk-conformance at the tag>`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change, and [SECURITY.md](SECURITY.md) to report a
+security problem.

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report a vulnerability in this SDK, or in the MFX Hub API it calls, privately:
+
+- through GitHub's **Report a vulnerability** button on this repository's Security tab, or
+- by email to **security@mfxhub.com**.
+
+Please do not open a public issue, pull request or discussion for a security problem.
+
+Tell us what you found, how to reproduce it, and what an attacker could do with it. Do not include
+real broker credentials or another person's data; if a proof needs a key, use one of your own
+development keys and say so.
+
+## What to expect
+
+- We acknowledge a report within two business days.
+- We tell you what we found and what we will do within ten business days.
+- We fix what is confirmed and say when the fix is released. We credit you in the release notes if
+  you want us to.
+
+## Supported versions
+
+Security fixes are made to the latest release of `@mfxhub/sdk`. Upgrade to it before reporting a problem
+you saw on an older one.
+
+## Handling credentials
+
+The SDK never stores or logs an API private key or a broker password: `SigningKey` and `Secret`
+render as `***` everywhere and cannot be pickled. If you believe a key has been exposed, write to
+security@mfxhub.com so it can be revoked at once, and use a new one.

package/dist/arguments.d.ts

@@ -0,0 +1,10 @@
+/** An id the API names as a uuid. Returned lower-case, as the API writes ids. */
+export declare function uuid(name: string, value: unknown): string;
+/**
+ * The idempotency key every write takes. It has no default: a default would be a value nobody
+ * chose, and the point of the key is that the caller can send the same one again and get the same
+ * answer back instead of a second order or terminal.
+ */
+export declare function idempotencyKey(value: unknown): string;
+/** A page size, when one is given: 1 to 200, as the API takes. */
+export declare function limit(value: unknown): number | undefined;

package/dist/arguments.js

@@ -0,0 +1,37 @@
+// Checks on what a caller passes, made before anything is sent. A refused argument is a TypeError
+// (the wrong kind of value) or a RangeError (the right kind, out of range), never a request.
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** An id the API names as a uuid. Returned lower-case, as the API writes ids. */
+export function uuid(name, value) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${name} is a uuid string; got ${typeof value}`);
+    }
+    if (!UUID.test(value))
+        throw new RangeError(`${name} is not a uuid: ${JSON.stringify(value)}`);
+    return value.toLowerCase();
+}
+/**
+ * The idempotency key every write takes. It has no default: a default would be a value nobody
+ * chose, and the point of the key is that the caller can send the same one again and get the same
+ * answer back instead of a second order or terminal.
+ */
+export function idempotencyKey(value) {
+    if (typeof value !== "string") {
+        throw new TypeError(`idempotencyKey is required on every write; got ${typeof value}`);
+    }
+    if (value.trim() === "" || value.length > 128) {
+        throw new RangeError("idempotencyKey is 1 to 128 characters");
+    }
+    return value;
+}
+/** A page size, when one is given: 1 to 200, as the API takes. */
+export function limit(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new TypeError(`limit is a whole number; got ${typeof value === "number" ? value : typeof value}`);
+    }
+    if (value < 1 || value > 200)
+        throw new RangeError(`limit is 1 to 200; got ${value}`);
+    return value;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,25 @@
+import type { MfxClient } from "./client.js";
+import type { components } from "./generated/api.js";
+/** One symbol's current quote, with its age and whether the market can be traded. */
+export type Quote = components["schemas"]["SymbolQuote"];
+/** Which of a tenant's servers and account types a symbol is meant on. */
+export interface QuoteOptions {
+    /** Needed when the symbol is on more than one of your servers (409 `ambiguous_symbol`). */
+    readonly serverId?: string;
+    /** Needed when the symbol is listed under more than one account type on that server. */
+    readonly accountType?: string;
+}
+/** The tenant's catalogue of brokers and symbols. */
+export declare class Catalog {
+    #private;
+    constructor(client: MfxClient);
+    /**
+     * The current quote for one symbol, read from one of your terminals on that broker's server.
+     * `state` says whether the market can be traded (`open`, `closed_session`, ...);
+     * `broker_time` is the broker's own clock, which is not UTC.
+     *
+     * @param brokerId the broker, from the catalogue
+     * @param symbol the broker's own symbol name (`EURUSD.sd`)
+     */
+    quote(brokerId: string, symbol: string, options?: QuoteOptions): Promise<Quote>;
+}

package/dist/catalog.js

@@ -0,0 +1,39 @@
+// `client.catalog`: what a tenant's brokers offer, and what it costs right now.
+//
+// This first slice is the quote. A quote is never returned without saying how old it is
+// (`age_s`): a stale quote reads exactly like a live one and gets acted on. Its prices are the
+// API's decimal strings, every digit kept.
+import { uuid } from "./arguments.js";
+/** The tenant's catalogue of brokers and symbols. */
+export class Catalog {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /**
+     * The current quote for one symbol, read from one of your terminals on that broker's server.
+     * `state` says whether the market can be traded (`open`, `closed_session`, ...);
+     * `broker_time` is the broker's own clock, which is not UTC.
+     *
+     * @param brokerId the broker, from the catalogue
+     * @param symbol the broker's own symbol name (`EURUSD.sd`)
+     */
+    async quote(brokerId, symbol, options = {}) {
+        const broker = uuid("brokerId", brokerId);
+        if (typeof symbol !== "string" || symbol === "") {
+            throw new TypeError("symbol is the broker's symbol name");
+        }
+        if (options.accountType !== undefined && typeof options.accountType !== "string") {
+            throw new TypeError("accountType is the account type's name");
+        }
+        const body = await this.#client.read({
+            method: "GET",
+            path: `/brokers/${broker}/symbols/${encodeURIComponent(symbol)}/quote`,
+            query: {
+                server_id: options.serverId === undefined ? undefined : uuid("serverId", options.serverId),
+                account_type: options.accountType,
+            },
+        });
+        return body;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `MfxClient`: one signed connection to the MFX Hub API.
+ *
+ * Every request is signed with the tenant's Ed25519 key. Reads that are rate limited are retried
+ * after the platform's own `Retry-After`; writes are never retried, because a retried write is a
+ * second order. Failures become typed errors from `errors.ts`.
+ */
+import { MfxApiError } from "./errors.js";
+import { RequestSigner, type SigningKey } from "./signing.js";
+import { Catalog } from "./catalog.js";
+import { Execution } from "./execution.js";
+import { MfxStream, type StreamOptions } from "./stream.js";
+import { Terminals } from "./terminals.js";
+/** Default time a single request may take. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** How many times a rate-limited read is tried again. */
+export declare const DEFAULT_READ_RETRIES = 3;
+/** What the key had left when MFX Hub last answered. */
+export interface Budget {
+    readonly remaining: number;
+    readonly source: string;
+}
+/** Options for {@link MfxClient}. */
+export interface ClientOptions {
+    /** Time one request may take, in milliseconds. */
+    readonly timeoutMs?: number;
+    /** How many times a rate-limited read is tried again. */
+    readonly readRetries?: number;
+    /** How the client waits between attempts; replaceable in tests. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** The fetch implementation; the runtime's own by default. */
+    readonly fetch?: typeof fetch;
+    /** The signer's clock, in epoch milliseconds; replaceable in tests. */
+    readonly clock?: () => number;
+    /** A number in [0, 1) for the backoff's jitter; replaceable in tests. */
+    readonly random?: () => number;
+}
+/** One request, as the resource modules describe it. */
+export interface RequestSpec {
+    readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** The path after the version, such as `/terminals/{id}`, with ids already filled in. */
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string | number | boolean | null | undefined>>;
+    readonly body?: unknown;
+    /** Required on every write; sent as the Idempotency-Key header. */
+    readonly idempotencyKey?: string;
+}
+/** The status and parsed body of an answer. */
+export interface Answer {
+    readonly status: number;
+    readonly headers: Headers;
+    readonly body: unknown;
+}
+/** A tenant's connection to MFX Hub. */
+export declare class MfxClient {
+    #private;
+    /** The terminals this key's tenant owns. */
+    readonly terminals: Terminals;
+    /** Order entry. Every call resolves to a result; none rejects. */
+    readonly execution: Execution;
+    /** Brokers, symbols and quotes. */
+    readonly catalog: Catalog;
+    /**
+     * @param baseUrl the API's base, including the version: `https://api.mfxhub.com/v1`, or
+     *   `https://api.dev.mfxhub.com/v1` for development
+     * @param keyId the API key's id
+     * @param privateKey its private key: PEM, the base64 of its 32 bytes, or a SigningKey
+     */
+    constructor(baseUrl: string, keyId: string, privateKey: string | Uint8Array | SigningKey, options?: ClientOptions);
+    /** The id of the key this client signs with. Safe to log, unlike the private key. */
+    get keyId(): string;
+    /** The REST base this client was pointed at. The stream's address is derived from it. */
+    get baseUrl(): string;
+    /** What the key had left when MFX Hub last answered; null before the first answer. */
+    get budget(): Budget | null;
+    /** The signer, for the stream's upgrade. Not part of the public surface. */
+    get signer(): RequestSigner;
+    /**
+     * Jittered exponential backoff for an attempt, when the platform gave no delay: up to 1 s, 2 s,
+     * 4 s ... capped at 30 s. The reads and the stream's reconnects share it, so they lean on this
+     * tenant's quota at the same rate.
+     */
+    backoffMs(attempt: number): number;
+    /**
+     * The multiplexed event stream, opened: subscribe, then iterate. Close it when done.
+     * Reconnects underneath, resuming what replays; see {@link MfxStream}.
+     */
+    stream(options?: StreamOptions): Promise<MfxStream>;
+    /** How the client waits; the stream uses it between reconnects. */
+    pause(ms: number): Promise<void>;
+    /** A read: retried after a 429 with the platform's own delay; a failure throws its typed error. */
+    read(spec: RequestSpec): Promise<unknown>;
+    /** A write: sent once, never retried; a failure throws its typed error. */
+    write(spec: RequestSpec): Promise<unknown>;
+    /** One attempt, signed afresh. Transport faults become MfxTransportError or MfxTimeout. */
+    send(spec: RequestSpec): Promise<Answer>;
+    toString(): string;
+}
+/** The typed error a failed answer means, or nothing for a success. */
+export declare function throwFor(answer: Answer, spec: RequestSpec): void;
+export { MfxApiError };