@cexyio/cexy 0.1.0-dev.5 → 0.1.0-dev.7

package/README.md

@@ -46,6 +46,8 @@ const cexy = new CexyClient({
 });
 
 const balances = await cexy.account.balances();
+// A sub-account's balances (parent account only; same shape, incl. held_incoming):
+const subBalances = await cexy.account.subAccountBalances("sub-account-id");
 const open = await cexy.trading.openOrders({ symbol: "BTC/USDT" });
 
 const placed = await cexy.trading.placeOrder({
@@ -62,6 +64,9 @@ await cexy.trading.cancelAll({ symbol: "BTC/USDT" }); // { symbol: null } = ever
 `cancelAll` requires `symbol`: the server treats a missing symbol as "every market", so the SDK makes
 you say so with `{ symbol: null }`. An unknown symbol throws `NotFoundError`.
 
+It also cancels stop orders that have not triggered yet (status `pending_trigger`) and releases
+their reservations, so nothing fires into the market after the call.
+
 One call handles at most 500 orders and puts each in exactly one list: `cancelled`, `already_closed`
 (it filled, was refused or was cancelled elsewhere first; not an error) or `failed`, with the reason in
 `failures` (`INVALID_STATE` for an order still being placed). `has_more: true` means more orders remain.
@@ -79,6 +84,8 @@ After a call without progress it waits 1, 2, 4, 8, then 15 s, and it stops after
 request (the loop owns the retries, so it never sends more than `maxRounds` requests): a 429 round waits its
 Retry-After, which counts against the budget; another retryable error (5xx, network) takes the next backoff
 step; a wait that would pass the budget ends the loop with `stopped: "time_budget"` and `last_error_code`.
+A wait imposed by the client rate limiter (e.g. `X-RateLimit-Remaining: 0` with a Reset) counts too: if it
+would pass the budget the loop stops without calling, with `last_error_code: "RATE_LIMITED"`.
 A non-retryable error (e.g. a key without the trade scope) throws `CancelAllInterruptedError` with the error
 and the partial result. The server allows 30 cancel-all calls per minute per account.
 
@@ -89,7 +96,7 @@ Give both `apiKey` and `apiSecret`, or neither: passing only one throws at const
 | `markets` | `list`, `get`, `orderbook`, `trades`, `iterateTrades`, `candles` | public |
 | `assets`, `networks`, `fees`, `pools` | `list`, `get` / `list` / `get` / `list`, `get` | public |
 | `time()`, `config()` | | public |
-| `account` | `balances`, `balance`, `ledger`, `notifications`, `subAccounts`, `apiKeys` (+ iterators) | read |
+| `account` | `balances`, `balance`, `ledger`, `notifications`, `subAccounts`, `subAccountBalances`, `apiKeys` (+ iterators) | read |
 | `exports` | `deposits`, `ledger`, `orders`, `trades`, `withdrawals` (CSV text) | read |
 | `wallet` | `deposits`, `deposit`, `withdrawals`, `withdrawal`, `withdrawalAddresses`, `depositAddress` (+ iterators) | read |
 | `trading` | `openOrders`, `order`, `orderByClientId`, `orderHistory`, `trades` (+ iterators) | read |
@@ -101,6 +108,13 @@ asset/network (later calls return the same one). Always use the `memo` too when
 
 There are no withdrawal or transfer methods: API keys cannot withdraw or transfer funds.
 
+**Held incoming transfers.** Each balance has `held_incoming`: incoming internal transfers still
+held, as `{ transfer_id, amount, available_at }`. Their sum is **already included in `locked`**, so
+never add them to `locked` or `total` again. There are at most 100 entries, soonest `available_at`
+first (millisecond precision), with no sender identity. An entry disappears once the transfer is
+released (the amount moves to `available`) or cancelled by the exchange. It is always an array
+(`[]` when none, including from servers that predate the field).
+
 ## Amounts
 
 Every amount is an exact decimal **string** (`"0.00150000"`), in responses and requests. JS numbers are
@@ -148,7 +162,8 @@ try {
 ## Retries and idempotency
 
 - Timeout per attempt: `timeoutMs` (default 10 s). Retries: `maxRetries` (default 3), exponential backoff with full jitter.
-- Retried: network errors, timeouts and responses with `retryable: true`.
+- Retried: network errors, timeouts and responses with `retryable: true` (and 409 `CONCURRENT_MODIFICATION`).
+  A 4xx is never retried except 429 and 409 `CONCURRENT_MODIFICATION`, whatever its body says.
 - 429 waits at least `Retry-After` / `details.retry_after_seconds`. Server wait hints are untrusted: unusable
   values are ignored, and a hint longer than 120 s (`MAX_SERVER_WAIT_MS`) is never waited: the call fails at
   once with `RateLimitError`, whose `retryAfterMs` still has the server's value. The client-side rate limiter
@@ -183,6 +198,22 @@ for await (const order of cexy.trading.iterateOrderHistory({ symbol: "BTC/USDT",
 // cap the total: cexy.account.iterateLedger({}, { maxItems: 500 })
 ```
 
+Each ledger entry's `reference` says what caused it, as a union told apart by `type` (`deposit`,
+`withdrawal`, `order`, `trade`, `transfer`, `adjustment`, `pool`, `futures_transfer`, `system`).
+Newer types the SDK does not know yet arrive unchanged instead of failing; narrow with
+`isLedgerReference`:
+
+```ts
+import { isLedgerReference } from "@cexyio/cexy";
+
+for await (const e of cexy.account.iterateLedger({}, { maxItems: 100 })) {
+  if (isLedgerReference(e.reference, "trade")) console.log(e.reference.trade_id);
+  else if (!isLedgerReference(e.reference)) console.log("new cause type:", e.reference.type);
+}
+```
+
+Ids (`OrderId`, `TradeId`, `UserId`, …) are plain strings; the SDK does not check their format.
+
 ## Rate limits
 
 The client has a token-bucket limiter: **100 requests/minute without a key** (the server allows 120/min
@@ -264,7 +295,7 @@ Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
 ## For tool builders
 
 The package exports its building blocks: the `OPERATIONS` table (method, path, auth and scope for each of the
-40 operations), all model types, the error classes, `paginate()`, `RateLimiter`, the `Authenticator`
+41 operations), all model types, the error classes, `paginate()`, `RateLimiter`, the `Authenticator`
 interface (HMAC signing will plug in here) and `userAgentSuffix` to identify your tool.
 
 ## Development

package/dist/index.cjs

@@ -139,13 +139,14 @@ var KNOWN_CODES = /* @__PURE__ */ new Set([
   "INTERNAL",
   "SERVICE_UNAVAILABLE",
   "UNDER_MAINTENANCE",
-  "ENGINE_OVERLOADED"
+  "ENGINE_OVERLOADED",
+  "PRICE_UNAVAILABLE"
 ]);
 var CLIENT_ERROR_CODES = { UNEXPECTED_REDIRECT: "UNEXPECTED_REDIRECT" };
 function isKnownErrorCode(code) {
   return KNOWN_CODES.has(code);
 }
-var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_SERVER_WAIT_MS = 12e4;
 function retryAfterMs(headers, details) {
   let best = null;
@@ -295,6 +296,7 @@ var OPERATIONS = {
   get_ledger: op("GET", "/api/v1/account/ledger", "api_key", "read", "account.ledger"),
   list_notifications: op("GET", "/api/v1/account/notifications", "api_key", "read", "account.notifications"),
   list_sub_accounts: op("GET", "/api/v1/account/sub-accounts", "api_key", "read", "account.subAccounts"),
+  sub_account_balances: op("GET", "/api/v1/account/sub-accounts/{id}/balances", "api_key", "read", "account.subAccountBalances"),
   list_api_keys: op("GET", "/api/v1/account/api-keys", "api_key", "read", "account.apiKeys"),
   // Exports (read)
   export_deposits: op("GET", "/api/v1/exports/deposits", "api_key", "read", "exports.deposits"),
@@ -325,6 +327,7 @@ var OPERATIONS = {
 
 // src/http.ts
 var IDEMPOTENT_OPS = /* @__PURE__ */ new Set(["join_pool", "exit_pool"]);
+var REPEAT_SAFE_MUTATIONS = /* @__PURE__ */ new Set(["join_pool", "exit_pool", "cancel_all"]);
 var BACKOFF_BASE_MS = 500;
 var BACKOFF_MAX_MS = 1e4;
 var Transport = class {
@@ -336,13 +339,14 @@ var Transport = class {
    * Sends a request with the standard retry policy: retryable errors and network failures are
    * retried. Pool join/exit carry an `Idempotency-Key` reused on every attempt (the server
    * honours it there, which makes their retries safe); the other mutations routed here
-   * (cancel-all) are naturally repeatable and send no key. `placeOrder` and `cancelOrder` use
-   * `attempt()` with their own policies.
+   * (cancel-all) are naturally repeatable and send no key. Any other mutation is sent once.
+   * `placeOrder` and `cancelOrder` use `attempt()` with their own policies.
    */
   async request(spec, opts = {}) {
     const info = OPERATIONS[spec.op];
     const idempotencyKey = IDEMPOTENT_OPS.has(spec.op) ? spec.idempotencyKey ?? opts.idempotencyKey ?? newId() : void 0;
-    const maxRetries = opts.maxRetries ?? this.config.maxRetries;
+    const repeatSafe = info.method === "GET" || REPEAT_SAFE_MUTATIONS.has(spec.op);
+    const maxRetries = repeatSafe ? opts.maxRetries ?? this.config.maxRetries : 0;
     for (let attempt = 0; ; attempt++) {
       try {
         return await this.attempt({ ...spec, idempotencyKey }, opts);
@@ -457,6 +461,7 @@ var Transport = class {
     const path = info.path.replace(/\{(\w+)\}/g, (_m, name) => {
       const v = pathParams[name];
       if (typeof v !== "string" || v === "") throw new CexyConfigError(`${info.sdkMethod}(): ${name} is required`);
+      if (v === "." || v === "..") throw new CexyConfigError(`${info.sdkMethod}(): ${name} must not be "." or ".."`);
       return encodeURIComponent(v);
     });
     const url = new URL(this.config.baseUrl.replace(/\/+$/, "") + path);
@@ -479,7 +484,11 @@ function serverHintMs(err) {
 }
 function isRetryable(err) {
   if (err instanceof CexyConnectionError) return true;
-  if (err instanceof CexyApiError) return err.retryable || err.code === "CONCURRENT_MODIFICATION";
+  if (err instanceof CexyApiError) {
+    const concurrent = err.code === "CONCURRENT_MODIFICATION";
+    if (err.status >= 400 && err.status < 500 && err.status !== 429 && !(err.status === 409 && concurrent)) return false;
+    return err.retryable || concurrent;
+  }
   return false;
 }
 function isAmbiguous(err) {
@@ -545,6 +554,17 @@ var RateLimiter = class {
       await this.#sleep(Math.min(MAX_BLOCK_MS, Math.ceil((1 - this.#tokens) * msPerToken)), signal);
     }
   }
+  /**
+   * How long `acquire()` would wait right now, in ms (0 when a request may go at once). Lets a
+   * caller with a time budget, such as the cancelAll untilDone loop, count the limiter's wait.
+   */
+  pendingWaitMs() {
+    this.#refill();
+    const block = this.#blockedUntil - this.#now();
+    if (block > 0) return block;
+    if (this.#tokens >= 1) return 0;
+    return Math.min(MAX_BLOCK_MS, Math.ceil((1 - this.#tokens) * (6e4 / this.#rpm)));
+  }
   /** Adapts to the server's rate-limit headers. Never raises the configured limit. */
   update(headers) {
     this.#refill();
@@ -740,12 +760,22 @@ var PoolsResource = class extends Resource {
     return this.data({ op: "exit_pool", pathParams: { symbol }, body }, opts);
   }
 };
+function withHeldIncoming(b) {
+  if (!b || typeof b !== "object" || Array.isArray(b.held_incoming)) return b;
+  return { ...b, held_incoming: [] };
+}
 var AccountResource = class extends Resource {
-  balances(opts) {
-    return this.data({ op: "list_balances" }, opts);
+  /**
+   * Balances per asset. `held_incoming` lists incoming internal transfers still held; their sum is
+   * already included in `locked` (never add it again). Always an array (`[]` when none).
+   */
+  async balances(opts) {
+    const rows = await this.data({ op: "list_balances" }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
   }
-  balance(asset, opts) {
-    return this.data({ op: "get_balance", pathParams: { asset } }, opts);
+  /** One asset's balance. `held_incoming`: incoming transfers still held, already inside `locked`. */
+  async balance(asset, opts) {
+    return withHeldIncoming(await this.data({ op: "get_balance", pathParams: { asset } }, opts));
   }
   ledger(params, opts) {
     return this.page({ op: "get_ledger", query: params }, opts);
@@ -762,6 +792,20 @@ var AccountResource = class extends Resource {
   subAccounts(opts) {
     return this.data({ op: "list_sub_accounts" }, opts);
   }
+  /**
+   * A sub-account's balances, read by its PARENT account: the same shape as `balances()`
+   * (zero balances omitted), including `held_incoming`, whose sum is already inside `locked`.
+   * The server currently returns them ordered by asset symbol; don't rely on the order.
+   * An id that is not one of the caller's sub-accounts (or a call with the sub-account's own
+   * key) gets `NotFoundError`; a sub-account's own key reads its balances with `balances()`.
+   * A malformed id gets 400 (`ValidationError`); a key without the `read` scope gets 403
+   * `FORBIDDEN` (`ForbiddenError`). `id` must be non-empty and not "." or ".."; it is sent as
+   * one URL path segment.
+   */
+  async subAccountBalances(id, opts) {
+    const rows = await this.data({ op: "sub_account_balances", pathParams: { id } }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
+  }
   /** Your API keys (metadata only; secrets are never returned). */
   apiKeys(opts) {
     return this.data({ op: "list_api_keys" }, opts);
@@ -1015,8 +1059,10 @@ var TradingResource = class extends Resource {
         if (progress) idle = 0;
         else waitMs = (CANCEL_BACKOFF_S[Math.min(idle++, CANCEL_BACKOFF_S.length - 1)] ?? 15) * 1e3;
       }
-      if (now() - start + waitMs >= budgetMs) {
+      const limiterMs = this.t.config.limiter?.pendingWaitMs() ?? 0;
+      if (now() - start + Math.max(waitMs, limiterMs) >= budgetMs) {
         stopped = "time_budget";
+        if (limiterMs > waitMs) lastErrorCode = "RATE_LIMITED";
         break;
       }
       if (waitMs > 0) await this.t.config.sleep(waitMs, opts?.signal);
@@ -1026,7 +1072,7 @@ var TradingResource = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.0-dev.5";
+var VERSION = "0.1.0-dev.7";
 var USER_AGENT = `cexy-typescript/${VERSION}`;
 
 // src/ws/emitter.ts
@@ -1878,6 +1924,23 @@ function canSetUserAgent() {
   return !(typeof g.window !== "undefined" && typeof g.window.document !== "undefined");
 }
 
+// src/ledger.ts
+var KNOWN_LEDGER_REFERENCE_TYPES = /* @__PURE__ */ new Set([
+  "deposit",
+  "withdrawal",
+  "order",
+  "trade",
+  "transfer",
+  "adjustment",
+  "pool",
+  "futures_transfer",
+  "system"
+]);
+function isLedgerReference(ref, type) {
+  if (typeof ref !== "object" || ref === null || typeof ref.type !== "string") return false;
+  return type === void 0 ? KNOWN_LEDGER_REFERENCE_TYPES.has(ref.type) : ref.type === type;
+}
+
 exports.AccountResource = AccountResource;
 exports.ApiKeyAuthenticator = ApiKeyAuthenticator;
 exports.AssetsResource = AssetsResource;
@@ -1928,6 +1991,7 @@ exports.assertAmountFields = assertAmountFields;
 exports.errorFromResponse = errorFromResponse;
 exports.isAmount = isAmount;
 exports.isKnownErrorCode = isKnownErrorCode;
+exports.isLedgerReference = isLedgerReference;
 exports.isLocalHost = isLocalHost;
 exports.isRetryable = isRetryable;
 exports.paginate = paginate;