@v3finance/core-sdk 0.1.0 → 0.2.1

package/src/client.ts

@@ -1,5 +1,15 @@
 import { HttpClient, seg, type ClientOptions } from './core/http.js'
-import type { CreateVaultBody, Health, VaultDetail } from './generated/types.js'
+import type {
+  BuildPathBody,
+  BuildPathResponse,
+  CreateVaultBody,
+  Health,
+  ParsePathBody,
+  ParsedPathResponse,
+  UserProfile,
+  VaultDetail,
+  VaultListItem,
+} from './generated/types.js'
 import { AddressesResource } from './resources/addresses.js'
 import { ApprovalsResource } from './resources/approvals.js'
 import { BalancesResource } from './resources/balances.js'
@@ -73,22 +83,31 @@ export interface VaultScope {
   readonly operations: OperationsResource
 }
 
-export interface VaultSummary {
-  id: string
-  code: string
-  name: string
-  [extra: string]: unknown
-}
+/**
+ * A vault as `vaults.list()` returns it.
+ *
+ * Listing and detail are DIFFERENT shapes, so this name can only stand for
+ * one of them. A list item carries `counts` (groups, invitations, policies,
+ * members) and a stripped-down `networks` (id, code, name, coinType); the
+ * detail response carries full `Network` records and the whole `routes` tree,
+ * and no counts at all. `vaults.get()` is therefore typed `VaultDetail`, not
+ * this.
+ *
+ * @deprecated Use `VaultListItem` directly. The name survives only because
+ * dropping an exported one breaks consumers: it used to be a hand-written
+ * interface that declared `id`, `code` and `name` and swept everything else
+ * into an index signature, which described neither shape — `counts` and
+ * `routes` alike arrived as `unknown`.
+ */
+export type VaultSummary = VaultListItem
 
-export interface Profile {
-  id: string
-  name: string | null
-  username: string | null
-  email: string | null
-  /** The account came from an invitation link and has no real email yet. */
-  needsEmail: boolean
-  [extra: string]: unknown
-}
+/**
+ * The caller's own profile — what `me.profile()` and `me.updateProfile()`
+ * both answer with.
+ *
+ * @deprecated Use `UserProfile` directly; the name is kept for consumers.
+ */
+export type Profile = UserProfile
 
 export class CoreClient {
   /** Low-level access for endpoints the resources do not cover yet. */
@@ -124,11 +143,25 @@ export class CoreClient {
   }
 
   readonly vaults = {
-    /** Administrators only: a plain member sees their own vault through `me.vault()`. */
-    list: (): Promise<VaultSummary[]> => this.http.request<VaultSummary[]>('GET', '/api/v1/vaults'),
+    /**
+     * Administrators only: a plain member sees their own vault through
+     * `me.vault()`. Not paginated and not filterable — the whole list comes
+     * back, newest first.
+     */
+    list: (): Promise<VaultListItem[]> =>
+      this.http.request<VaultListItem[]>('GET', '/api/v1/vaults'),
 
-    get: (code: string): Promise<VaultSummary> =>
-      this.http.request<VaultSummary>('GET', `/api/v1/vaults/${seg(code)}`),
+    /**
+     * Full configuration of one vault: every connected network and the whole
+     * `routes` tree, disabled variants included.
+     *
+     * Open to any MEMBER of the vault, unlike `list()`, which is
+     * administrator-only (an administrator passes the membership check too).
+     * The richer payload is also why the return type differs from a list
+     * item: see `VaultSummary`.
+     */
+    get: (code: string): Promise<VaultDetail> =>
+      this.http.request<VaultDetail>('GET', `/api/v1/vaults/${seg(code)}`),
 
     /** Administrators only. */
     create: (input: CreateVaultBody): Promise<VaultDetail> =>
@@ -140,15 +173,46 @@ export class CoreClient {
      * Use these rather than building the string yourself: the path is written
      * WITHOUT apostrophes (`m/44/195/…`, not `m/44'/…`), and the segment
      * order comes from the vault's own configuration, not from a convention.
+     *
+     * Both are open to any MEMBER of the vault; they are not
+     * administrator-only.
+     *
+     * `values` is keyed by `Route.code` and the generated type says only
+     * `unknown` per entry, because the schema's `string | number` union does
+     * not survive generation. What the server accepts: for a static route a
+     * variant `code` or its numeric `pathId`, for a dynamic route an integer
+     * in `[0, 2^31-1]`. A missing route, an unknown variant or a disabled one
+     * is a 400, not a silently skipped segment.
      */
-    buildDerivationPath: (code: string, body: unknown): Promise<unknown> =>
-      this.http.request('POST', `/api/v1/vaults/${seg(code)}/derivation-path/build`, { body }),
+    buildDerivationPath: (code: string, body: BuildPathBody): Promise<BuildPathResponse> =>
+      this.http.request<BuildPathResponse>(
+        'POST',
+        `/api/v1/vaults/${seg(code)}/derivation-path/build`,
+        { body },
+      ),
 
-    parseDerivationPath: (code: string, body: unknown): Promise<unknown> =>
-      this.http.request('POST', `/api/v1/vaults/${seg(code)}/derivation-path/parse`, { body }),
+    /**
+     * Breaks a path back into the network and one entry per route.
+     *
+     * `segments[].variant` is absent for a dynamic route — that is the normal
+     * case, not a lookup failure. For a static route it is present even when
+     * the variant is disabled, so that legacy addresses still parse.
+     */
+    parseDerivationPath: (code: string, body: ParsePathBody): Promise<ParsedPathResponse> =>
+      this.http.request<ParsedPathResponse>(
+        'POST',
+        `/api/v1/vaults/${seg(code)}/derivation-path/parse`,
+        { body },
+      ),
   }
 
-  /** Liveness probe. Needs no authentication. */
+  /**
+   * Liveness probe. Needs no authentication.
+   *
+   * It answers "is the worker deployed at all?" and nothing more: the handler
+   * never touches the database, so a healthy answer does NOT mean D1 is
+   * reachable. Use a real read for that.
+   */
   health(): Promise<Health> {
     return this.http.request<Health>('GET', '/')
   }

package/src/core/errors.ts

@@ -5,14 +5,30 @@
  * wrapper has three gaps the client has to close itself — otherwise a precise
  * error turns into "something went wrong":
  *
- *   1. Bodies without an `error` key pass through untouched. Batch sharing
- *      endpoints answer 400 with `{results:[…]}`, which is not a failure of
- *      the whole call but "some subjects were rejected", and has to be read
- *      item by item.
- *   2. Validation failures arrive as a plain string — `{error: "path: msg"}`
- *      — with no code and no details.
- *   3. Inside a batch result `message` equals the code (`{code:"X",
- *      message:"X"}`), so it must never be shown to a person as-is.
+ *   1. Bodies without an `error` key pass through untouched — the wrapper
+ *      keys off that one field. Batch sharing endpoints answer 400 with
+ *      `{results:[…]}`, which is not a failure of the whole call but "some
+ *      subjects were rejected", and has to be read item by item.
+ *   2. Non-JSON bodies have no wrapper at all: the layer leaves by
+ *      content-type, and a thrown `HTTPException` carries its own response
+ *      past it. So a 502 from the edge, a WAF 403 or a platform 429 arrive as
+ *      text. `core/http.ts` reduces a short one to a flat `{error: "…"}`
+ *      (dropping HTML pages) before it reaches this parser, which is why the
+ *      flat string shape below is still read — and why the per-status
+ *      fallback wording here is what a person ends up seeing.
+ *   3. `message` sometimes IS the code. Handlers answer `{error: "<CODE>",
+ *      code: "<CODE>"}` and batch items carry `{code:"X", message:"X"}`; the
+ *      wrapper copies the former into `message` faithfully. A code is not a
+ *      sentence, so it must never be shown to a person as-is.
+ *
+ * What is NOT a gap any more: zod validation failures. The route hook does
+ * build a flat `{error: "amount: Required; …"}` (backend
+ * `openapi/common.ts`), but that is an intermediate form.
+ * `middleware/errorEnvelope` rewraps every JSON body carrying a string
+ * `error` into the canonical envelope, `code` derived from the status —
+ * `BAD_REQUEST` here, because the hook sets none of its own. The same layer
+ * answers an unmatched path and an uncaught throw. Reading `body.error` as a
+ * string against today's API therefore hands you an object.
  *
  * Because of that `code` is always present here: either the server sent one,
  * or it is derived from the HTTP status. Branch on `code`, display `message`.
@@ -73,29 +89,37 @@ export function hasCode(e: unknown, ...codes: readonly string[]): boolean {
 }
 
 /**
- * Status to code, mirroring the mapping the API uses, so that both sides call
- * the same thing by the same name.
+ * Status to code, used only when a body carried no code of its own: a proxy's
+ * HTML 502, a platform 429, an empty body.
+ *
+ * The names are the API's own names for the same statuses, so that one
+ * condition has one name whichever side produced it. 502 and 504 are the
+ * exception — the API has no envelope for them, they arrive from the edge.
  */
 export function codeFromStatus(status: number): string {
   switch (status) {
     case 400:
       return 'BAD_REQUEST'
     case 401:
-      return 'UNAUTHORIZED'
+      return 'UNAUTHENTICATED'
     case 403:
       return 'FORBIDDEN'
     case 404:
       return 'NOT_FOUND'
     case 409:
       return 'CONFLICT'
+    case 413:
+      return 'PAYLOAD_TOO_LARGE'
     case 422:
-      return 'UNPROCESSABLE'
+      return 'UNPROCESSABLE_ENTITY'
     case 429:
       return 'RATE_LIMITED'
+    case 501:
+      return 'NOT_IMPLEMENTED'
     case 502:
       return 'BAD_GATEWAY'
     case 503:
-      return 'UNAVAILABLE'
+      return 'SERVICE_UNAVAILABLE'
     case 504:
       return 'GATEWAY_TIMEOUT'
     default:
@@ -139,7 +163,12 @@ export function parseErrorBody(status: number, body: unknown, endpoint?: string)
     return make(message, code, o.details)
   }
 
-  // Shape 2 — a validation failure as a string: {error: "path: msg; …"}
+  // Shape 2 — a flat string `error`. No longer how validation failures reach
+  // a client (the envelope rewraps those into Shape 1), so the live producer
+  // is `core/http.ts`, which folds a short non-JSON error body into this
+  // shape. The sibling `code` is still read: handlers do put one next to a
+  // string `error`, and an older deployment without the envelope layer would
+  // deliver exactly that.
   if (typeof inner === 'string' && inner) {
     const flat = (body as { code?: unknown }).code
     const code = typeof flat === 'string' && flat ? flat : fallbackCode
@@ -195,7 +224,12 @@ export const timeoutError = (ms: number, endpoint?: string): CoreError =>
     kind: 'timeout',
     code: 'TIMEOUT',
     status: null,
-    message: `The server did not answer within ${Math.round(ms / 1000)}s`,
+    // Sub-second timeouts rounded to `0s`, which reads as "no time was
+    // allowed" rather than "400ms was". Below a second the unit changes
+    // instead of the number; a whole second keeps the shorter wording.
+    message: `The server did not answer within ${
+      ms < 1000 ? `${Math.round(ms)}ms` : `${Math.round(ms / 1000)}s`
+    }`,
     ...(endpoint === undefined ? {} : { endpoint }),
   })
 

package/src/core/gated.ts

@@ -4,8 +4,10 @@
  *
  *   201 — applied immediately (policy allowed it without signatures);
  *   202 — queued for approval, funds are reserved, nothing has moved yet;
- *   200 — a replay of the same idempotency key: nothing happened now, the
- *         existing operation came back (no second broadcast).
+ *   200 — on a transfer: a replay of the same idempotency key, nothing
+ *         happened now and the existing operation came back (no second
+ *         broadcast). Everywhere else: an ordinary applied success, because
+ *         an edit is not a creation and answers 200 (see `replayOn200`).
  *
  * The body can be identical: a transfer returns `{transaction}` in all three.
  * A client that reads only the body will say "sent" where the truth is
@@ -13,14 +15,25 @@
  * frozen.
  *
  * `replayed` is kept separate from `applied` on purpose. A replay means the
- * previous attempt DID reach the server and only the answer was lost, so the
- * person should be told "already sent", not "sent" a second time.
+ * previous attempt DID reach the server and only the answer was lost — not
+ * that it succeeded. The body is that operation as it stands now: a replayed
+ * transfer may have gone out, be waiting for signatures, be still executing
+ * or have failed, and only its own status says which.
  */
 
 export type GatedOutcome = 'applied' | 'pending' | 'replayed'
 
+/**
+ * `status` is the status the server ACTUALLY answered, which is why `applied`
+ * carries `200 | 201` rather than 201 alone: an ordinary 200 success is an
+ * applied operation too (updating a counterparty, editing a label — anything
+ * gated that is not a creation). The field used to be hard-coded to 201 for
+ * those, so every gated method except `transfers.send` reported a status the
+ * server never sent, into logs and error reports where it is the one thing
+ * worth trusting. Branch on `outcome`; read `status` when you need the fact.
+ */
 export type Gated<TApplied, TPending = TApplied> =
-  | { readonly outcome: 'applied'; readonly status: 201; readonly data: TApplied }
+  | { readonly outcome: 'applied'; readonly status: 200 | 201; readonly data: TApplied }
   | { readonly outcome: 'replayed'; readonly status: 200; readonly data: TApplied }
   | { readonly outcome: 'pending'; readonly status: 202; readonly data: TPending }
 
@@ -33,6 +46,13 @@ export type Gated<TApplied, TPending = TApplied> =
  * success. Telling a person "already sent" after a plain edit would be as
  * wrong as telling them "done" after a replay, so each caller states which
  * of the two it is instead of the helper guessing.
+ *
+ * Which also means `outcome: 'replayed'` is UNREACHABLE for every gated
+ * method other than `transfers.send`: replay protection needs an idempotency
+ * key, and the transfer body is the only place the API takes one. The
+ * three-way `switch` in `docs/concepts.md` is right for a transfer; beside a
+ * counterparty edit its `case 'replayed'` is dead, and it is not evidence
+ * that such an edit can come back as a replay.
  */
 export function toGated<TApplied, TPending>(
   status: number,
@@ -43,7 +63,7 @@ export function toGated<TApplied, TPending>(
     case 200:
       return options.replayOn200
         ? { outcome: 'replayed', status: 200, data: data as TApplied }
-        : { outcome: 'applied', status: 201, data: data as TApplied }
+        : { outcome: 'applied', status: 200, data: data as TApplied }
     case 201:
       return { outcome: 'applied', status: 201, data: data as TApplied }
     case 202:
@@ -56,7 +76,11 @@ export function toGated<TApplied, TPending>(
   }
 }
 
-/** Narrowing: the operation ran, now or earlier, and money moved. */
+/**
+ * Narrowing: `applied` or `replayed`. For `applied` the operation ran now.
+ * For `replayed` it only existed already — whether money moved is in the
+ * body's own status, not in this check.
+ */
 export function isApplied<A, P>(
   r: Gated<A, P>,
 ): r is Extract<Gated<A, P>, { outcome: 'applied' | 'replayed' }> {

package/src/core/http.ts

@@ -1,5 +1,6 @@
 import {
   abortedError,
+  isCoreError,
   networkError,
   parseError,
   parseErrorBody,
@@ -88,15 +89,19 @@ export interface RequestOptions {
   signal?: AbortSignal | undefined
   timeoutMs?: number | undefined
   /**
-   * Attempt key, sent as the `idempotency-key` header.
+   * Attempt key. ACCEPTED AND IGNORED BY THE TRANSPORT — the working place
+   * for it is the request BODY, the way `transfers.send` passes it.
    *
-   * THE SERVER DOES NOT READ THIS HEADER TODAY. Replay protection on money
-   * paths is resolved from the `idempotencyKey` FIELD OF THE BODY — that is
-   * what `transfers.send` uses, and that is what protects it. The header is
-   * here for the day the API starts honouring it; until then, calling a
-   * money endpoint through the low-level client and passing the key only
-   * here buys you nothing, and a retry after a timeout sends the money
-   * twice. Put the key in the body.
+   * It used to go out as an `idempotency-key` header. The server has never
+   * read that header, which by itself merely bought nothing; in a browser it
+   * cost the whole request. The API's CORS preflight allows exactly
+   * `Content-Type` and `Authorization` (`allowHeaders`, backend
+   * `src/index.ts`), so the extra header failed the preflight and the call
+   * was never sent at all — a money request that could not reach the server,
+   * and a "network error" that no retry explains. Replay protection is
+   * resolved from the `idempotencyKey` FIELD of the body and nowhere else.
+   *
+   * @deprecated The transport sends this nowhere. Put the key in the body.
    */
   idempotencyKey?: string | undefined
   headers?: Record<string, string> | undefined
@@ -152,13 +157,27 @@ export class HttpClient {
   constructor(options: ClientOptions & { baseUrl: string }) {
     this.baseUrl = options.baseUrl.replace(/\/+$/, '')
     this.#options = options
-    const f = options.fetch ?? globalThis.fetch
-    if (typeof f !== 'function') {
+    const custom = options.fetch
+    if (typeof (custom ?? globalThis.fetch) !== 'function') {
       throw new Error(
         '@v3finance/core-sdk: fetch is unavailable in this runtime — pass one to the client options.',
       )
     }
-    this.#fetch = f
+    // NEVER store the function and call it as `this.#fetch(…)`. A private
+    // field call passes the client as the receiver, and a browser's `fetch`
+    // checks its receiver: anything but the window is
+    // `TypeError: Illegal invocation`, thrown before a single byte leaves.
+    // Node and React Native do not check, which is how every request from a
+    // web page failed while the whole test suite passed — and since a
+    // `TypeError` out of `fetch` is what a dropped connection looks like, the
+    // failure surfaced as a "network error" on a perfectly good network.
+    //
+    // The wrapper calls with no receiver at all. Without a custom fetch the
+    // global one is looked up per call rather than captured here, so whatever
+    // patches it later (instrumentation, a mock server) is still honoured.
+    this.#fetch = custom
+      ? (input, init) => custom(input, init)
+      : (input, init) => globalThis.fetch(input, init)
     this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
   }
 
@@ -174,13 +193,20 @@ export class HttpClient {
    * time. Read it with `.blob()`, `.text()` or `.arrayBuffer()`.
    */
   async fetchRaw(method: string, path: string, options: RequestOptions = {}): Promise<Response> {
-    const { response, endpoint } = await this.#send(method, path, options)
+    // The body is touched only when the call FAILED — and then by the same
+    // reader a JSON call uses, so one 502 from the edge produces one message
+    // whichever method asked for it. The two used to disagree: this one fell
+    // back to neutral wording while `requestRaw` put the proxy's HTML page
+    // into `message`.
+    //
+    // On success the response is handed over unread, which also means the
+    // timeout ends at the headers here: the file body is the caller's to read
+    // and to bound, with their own signal.
+    const { response, endpoint, payload } = await this.#send(method, path, options, (r, ep) =>
+      r.ok ? Promise.resolve(undefined) : readJsonBody(r, ep),
+    )
     if (!response.ok) {
-      const body = await response
-        .clone()
-        .json()
-        .catch(() => undefined)
-      const error = parseErrorBody(response.status, body, endpoint)
+      const error = parseErrorBody(response.status, payload, endpoint)
       if (response.status === 401 && this.#options.onUnauthorized) {
         await this.#options.onUnauthorized(error)
       }
@@ -195,26 +221,36 @@ export class HttpClient {
     path: string,
     options: RequestOptions = {},
   ): Promise<RawResponse<T>> {
-    const { response, endpoint } = await this.#send(method, path, options)
-
-    const data = await readBody(response, endpoint)
+    const { response, endpoint, payload } = await this.#send(method, path, options, readJsonBody)
 
     if (!response.ok) {
-      const error = parseErrorBody(response.status, data, endpoint)
+      const error = parseErrorBody(response.status, payload, endpoint)
       if (response.status === 401 && this.#options.onUnauthorized) {
         await this.#options.onUnauthorized(error)
       }
       throw error
     }
 
-    return { status: response.status, data: data as T, headers: response.headers }
+    return { status: response.status, data: payload as T, headers: response.headers }
   }
 
+  /**
+   * One attempt: headers out, body in, cleanup.
+   *
+   * The body is read HERE, through `readPayload`, instead of by the caller
+   * afterwards — because the timeout and the caller's signal have to stay
+   * armed until the body is in hand. Headers arrive first and the body streams
+   * after; with the timer cleared at the headers, a server that answers and
+   * then stalls mid-body left a request hanging with nothing to end it. On a
+   * money path that is a transfer whose outcome is never learned, and no
+   * retry decision either.
+   */
   async #send(
     method: string,
     path: string,
     options: RequestOptions,
-  ): Promise<{ response: Response; endpoint: string }> {
+    readPayload: (response: Response, endpoint: string) => Promise<unknown>,
+  ): Promise<{ response: Response; endpoint: string; payload: unknown }> {
     const endpoint = `${method.toUpperCase()} ${path}`
     const url = `${this.baseUrl}${path}${serializeQuery(options.query)}`
     const timeoutMs = options.timeoutMs ?? this.#timeoutMs
@@ -227,7 +263,14 @@ export class HttpClient {
       ...options.headers,
     }
     if (options.body !== undefined) headers['content-type'] = 'application/json'
-    if (options.idempotencyKey) headers['idempotency-key'] = options.idempotencyKey
+    // NOTHING ELSE IS ADDED BY DEFAULT, and that is a browser constraint
+    // rather than minimalism: the API's CORS preflight allows exactly
+    // `Content-Type` and `Authorization`, so any further header of ours makes
+    // the preflight fail and the request is never sent. These three are safe —
+    // `accept` is CORS-safelisted, and `user-agent` is a forbidden header name
+    // the browser drops before it can be preflighted (it still reaches the API
+    // from Node and React Native, which is where it is useful). A header
+    // passed in through `headers` is the caller's own risk.
 
     // A timer of our own on top of the caller's signal: `AbortSignal.timeout`
     // is missing in some React Native runtimes, and "the caller cancelled" has
@@ -242,47 +285,128 @@ export class HttpClient {
     const onExternalAbort = () => controller.abort()
     options.signal?.addEventListener('abort', onExternalAbort, { once: true })
 
-    let response: Response
+    const classify = (cause: unknown): CoreError =>
+      transportError(cause, { timedOut, timeoutMs, endpoint, signal: options.signal })
+
+    // The cleanup is an OUTER finally, so it also runs when `onTokenRotated`
+    // throws — a caller's storage failure should not leave our timer armed,
+    // ready to abort an unrelated stream seconds later.
     try {
-      response = await this.#fetch(url, {
-        method: method.toUpperCase(),
-        headers,
-        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
-        ...(this.#options.credentials === undefined
-          ? {}
-          : { credentials: this.#options.credentials }),
-        signal: controller.signal,
-      })
-    } catch (cause) {
-      if (timedOut) throw timeoutError(timeoutMs, endpoint)
-      if (options.signal?.aborted) throw abortedError(endpoint)
-      throw networkError(cause, endpoint)
+      let response: Response
+      try {
+        response = await this.#fetch(url, {
+          method: method.toUpperCase(),
+          headers,
+          ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+          ...(this.#options.credentials === undefined
+            ? {}
+            : { credentials: this.#options.credentials }),
+          signal: controller.signal,
+        })
+      } catch (cause) {
+        throw classify(cause)
+      }
+
+      // Rotation arrives on successful responses too, and is taken BEFORE the
+      // body: the token is valid whatever the body turns out to be, and a
+      // rotation we drop signs the client out at the next one.
+      const rotated = response.headers.get(ROTATED_TOKEN_HEADER)
+      if (rotated && this.#options.onTokenRotated) await this.#options.onTokenRotated(rotated)
+
+      let payload: unknown
+      try {
+        payload = await readPayload(response, endpoint)
+      } catch (cause) {
+        throw classify(cause)
+      }
+
+      return { response, endpoint, payload }
     } finally {
       clearTimeout(timer)
       options.signal?.removeEventListener('abort', onExternalAbort)
     }
-
-    // Rotation arrives on successful responses too.
-    const rotated = response.headers.get(ROTATED_TOKEN_HEADER)
-    if (rotated && this.#options.onTokenRotated) await this.#options.onTokenRotated(rotated)
-
-    return { response, endpoint }
   }
 }
 
+/**
+ * Names a transport failure, of the request or of the body behind it.
+ *
+ * The distinction is not cosmetic on a money path: a timeout may have been
+ * applied server-side (retry only with the same idempotency key), a cancel is
+ * the caller's own decision and must not be shown as a failure, and a network
+ * error never left the device. A `CoreError` arrives already named — the body
+ * reader raises one when a successful response is not the JSON the contract
+ * promises — and is passed through, so "the contract is wrong" is not reported
+ * as "the network is down".
+ *
+ * Our own timeout wins over the caller's signal, and both win over the cause:
+ * an abort mid-body surfaces as the abort that caused it, not as the opaque
+ * `AbortError` the stream rejects with.
+ */
+function transportError(
+  cause: unknown,
+  ctx: {
+    timedOut: boolean
+    timeoutMs: number
+    endpoint: string
+    signal?: AbortSignal | undefined
+  },
+): CoreError {
+  if (ctx.timedOut) return timeoutError(ctx.timeoutMs, ctx.endpoint)
+  if (ctx.signal?.aborted) return abortedError(ctx.endpoint)
+  if (isCoreError(cause)) return cause
+  return networkError(cause, ctx.endpoint)
+}
+
+/** The longest fragment of a non-JSON error body worth carrying into a message. */
+const MAX_PLAIN_ERROR_CHARS = 200
+
 /**
  * An empty body (204, DELETE) is `undefined`, not a parse failure. Invalid
  * JSON on a SUCCESSFUL status is a failure: the contract is not what we think
- * it is, and returning `undefined` quietly is worse than throwing. On an error
- * status the text is kept as-is for `parseErrorBody` to read.
+ * it is, and returning `undefined` quietly is worse than throwing.
+ *
+ * A read that fails halfway is no longer swallowed. It used to be caught into
+ * an empty string, which turned a truncated response — a dropped connection,
+ * our own timeout firing while the body streamed — into `data: undefined`
+ * typed as the shape the caller asked for: a failure wearing the face of a
+ * successful empty answer, and on a balance or a transfer the worst possible
+ * disguise. The rejection now travels out to `transportError`, which names it
+ * a timeout, a cancel or a network failure.
  */
-async function readBody(response: Response, endpoint: string): Promise<unknown> {
-  const text = await response.text().catch(() => '')
+async function readJsonBody(response: Response, endpoint: string): Promise<unknown> {
+  const text = await response.text()
   if (!text) return undefined
   try {
     return JSON.parse(text) as unknown
   } catch (cause) {
     if (response.ok) throw parseError(cause, endpoint)
-    return { error: text }
+    return plainTextError(text)
+  }
+}
+
+/**
+ * A non-JSON error body reduced to something showable — or to nothing.
+ *
+ * Who sends these: everything in front of the API, never the API itself. A
+ * 502/504 while the worker is being replaced, a 403 from a WAF, a platform
+ * 429 — they answer with a whole HTML page (2318 bytes in one measured case).
+ * Passing that on as `{error: text}` put the page into `message`, which is the
+ * one field meant to be read by a person.
+ *
+ * Markup is therefore dropped and `parseErrorBody` falls back to its own
+ * wording for the status. A short line of plain text is kept instead of being
+ * dropped with it, because a proxy occasionally says something the status does
+ * not ("upstream connect error", "no healthy upstream").
+ */
+function plainTextError(text: string): unknown {
+  // A leading `<` catches HTML and XML error documents alike; neither is ours.
+  const collapsed = text.trim().replace(/\s+/g, ' ')
+  if (!collapsed || collapsed.startsWith('<')) return undefined
+  return {
+    error:
+      collapsed.length > MAX_PLAIN_ERROR_CHARS
+        ? `${collapsed.slice(0, MAX_PLAIN_ERROR_CHARS)}…`
+        : collapsed,
   }
 }