@ninedeploy/sdk 0.10.6 → 0.16.0

package/src/resources/volumes.ts

@@ -0,0 +1,138 @@
+// Client surface: volumes, containers, serviceVolumes.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  CreateServiceVolumeAttachmentInput,
+  ServiceVolumeAttachment,
+  UpdateServiceVolumeAttachmentInput,
+  VolumeFileEntry,
+  VolumeFileWriteInput,
+  VolumePathCreateInput,
+  VolumeCreateInput,
+} from '@ninedeploy/schemas';
+import { apiGetUrl } from '../apiPath.js';
+import type { VolumeListEntry, VolumeCreateResult, ContainerInspectData, ContainerComposeData } from '../types.js';
+import type { Transport } from '../transport.js';
+
+export interface VolumesApi {
+  volumes: {
+    /**
+     * Managed volumes on the panel host or (0.16 T8) with `serverId` on a
+     * node, through its agent; node entries carry `serverId`. An older agent
+     * answers 422 `node_agent_outdated`.
+     */
+    list: (options?: { serverId?: number }) => Promise<VolumeListEntry[]>;
+    /** Delete a retained volume; with `serverId` (r466) on that node. */
+    remove: (name: string, options?: { serverId?: number }) => Promise<void>;
+    /**
+     * 0.16 T8: create a managed volume (`nd-svc-*` / `nd-db-*`) on the panel
+     * host or, with `serverId`, on a node. An existing volume answers 409
+     * `node_volume_exists`.
+     */
+    create: (input: VolumeCreateInput) => Promise<VolumeCreateResult>;
+    prune: () => Promise<{ ok: boolean; deleted: number; freedBytes: number }>;
+    /** File manager: list a directory inside the volume. */
+    listFiles: (name: string, path?: string) => Promise<{ path: string; entries: VolumeFileEntry[] }>;
+    /** File manager: read a file (base64 content). */
+    readFile: (name: string, path: string) => Promise<{ content: string; encoding: 'utf8' | 'base64' }>;
+    /** File manager: write/overwrite a file (base64 content). */
+    writeFile: (name: string, input: VolumeFileWriteInput) => Promise<{ ok: boolean }>;
+    /** File manager: create a directory. */
+    mkdir: (name: string, input: VolumePathCreateInput) => Promise<{ ok: boolean }>;
+    /** File manager: delete a file or directory (recursive). */
+    deleteFile: (name: string, path: string) => Promise<void>;
+  };
+  containers: {
+    inspect: (container: string) => Promise<ContainerInspectData>;
+    compose: (container: string) => Promise<ContainerComposeData>;
+    /** File manager: list a directory inside the container. */
+    listFiles: (container: string, path?: string) => Promise<{ path: string; entries: VolumeFileEntry[] }>;
+    /** File manager: read a file (base64 content). */
+    readFile: (container: string, path: string) => Promise<{ content: string; encoding: 'utf8' | 'base64' }>;
+    /** File manager: write/overwrite a file (base64 content). */
+    writeFile: (container: string, input: VolumeFileWriteInput) => Promise<{ ok: boolean }>;
+    /** File manager: create a directory. */
+    mkdir: (container: string, input: VolumePathCreateInput) => Promise<{ ok: boolean }>;
+    makeDir: (container: string, input: VolumePathCreateInput) => Promise<{ ok: boolean }>;
+    /** File manager: delete a file or directory (recursive). */
+    deleteFile: (container: string, path: string) => Promise<void>;
+    deletePath: (container: string, path: string) => Promise<void>;
+  };
+  /** Per-service additional volume attachments. Distinct from the instance-wide
+   * `volumes` namespace (which lists every Docker volume on the host). The
+   * list endpoint returns runtime-computed metadata (size, in-use, sharing);
+   * the create/update endpoints return the database row only. */
+  serviceVolumes: {
+    list: (serviceId: number) => Promise<Array<ServiceVolumeAttachment & { sizeBytes: number; inUse: boolean; sharedWith: number }>>;
+    /** Attach an existing managed volume or create a new one and attach it. */
+    create: (serviceId: number, input: CreateServiceVolumeAttachmentInput) => Promise<{ attachment: ServiceVolumeAttachment; deploymentId: number }>;
+    update: (serviceId: number, attachmentId: number, input: UpdateServiceVolumeAttachmentInput) => Promise<{ attachment: ServiceVolumeAttachment; deploymentId: number }>;
+    /** Detach. The underlying Docker volume is NOT deleted (data persists). */
+    remove: (serviceId: number, attachmentId: number) => Promise<void>;
+    /** Delete a first-boot-baked config file from the volume and queue a
+     *  redeploy so the app regenerates it from the current environment
+     *  (WordPress wp-config.php et al.). Exactly one of `attachmentId` /
+     *  `volumeName` must be set; `filePath` is a single path segment. */
+    repairConfig: (
+      serviceId: number,
+      input: { filePath: string; attachmentId?: number; volumeName?: string },
+    ) => Promise<{ ok: boolean; deploymentId: number }>;
+  };
+}
+
+export function volumesApi(t: Transport): VolumesApi {
+  const { get, send, request } = t;
+  return {
+    volumes: {
+      list: (options) => get<VolumeListEntry[]>(apiGetUrl('/v1/volumes', { serverId: options?.serverId })),
+      create: (input) => send<VolumeCreateResult>('POST', '/v1/volumes', input),
+      listFiles: (name, path = '') =>
+        get<{ path: string; entries: VolumeFileEntry[] }>(`/v1/volumes/${encodeURIComponent(name)}/files?path=${encodeURIComponent(path)}`),
+      readFile: (name, path) =>
+        get<{ content: string; encoding: 'utf8' | 'base64' }>(`/v1/volumes/${encodeURIComponent(name)}/files/content?path=${encodeURIComponent(path)}`),
+      writeFile: (name, input) => send<{ ok: boolean }>('PUT', `/v1/volumes/${encodeURIComponent(name)}/files`, input),
+      mkdir: (name, input) => send<{ ok: boolean }>('POST', `/v1/volumes/${encodeURIComponent(name)}/files/dir`, input),
+      deleteFile: async (name, path) => {
+        await request(`/v1/volumes/${encodeURIComponent(name)}/files?path=${encodeURIComponent(path)}`, { method: 'DELETE' });
+      },
+      remove: async (name, options) => {
+        const node = options?.serverId === undefined ? '' : `?serverId=${options.serverId}`;
+        await request(`/v1/volumes/${encodeURIComponent(name)}${node}`, { method: 'DELETE' });
+      },
+      prune: () => send<{ ok: boolean; deleted: number; freedBytes: number }>('POST', '/v1/volumes/prune'),
+    },
+    containers: {
+      inspect: (container) => get<ContainerInspectData>(`/v1/containers/${encodeURIComponent(container)}/inspect`),
+      compose: (container) => get<ContainerComposeData>(`/v1/containers/${encodeURIComponent(container)}/compose`),
+      listFiles: (container, path = '/') =>
+        get<{ path: string; entries: VolumeFileEntry[] }>(`/v1/containers/${encodeURIComponent(container)}/files?path=${encodeURIComponent(path)}`),
+      readFile: (container, path) =>
+        get<{ content: string; encoding: 'utf8' | 'base64' }>(`/v1/containers/${encodeURIComponent(container)}/files/content?path=${encodeURIComponent(path)}`),
+      writeFile: (container, input) => send<{ ok: boolean }>('PUT', `/v1/containers/${encodeURIComponent(container)}/files`, input),
+      mkdir: (container, input) => send<{ ok: boolean }>('POST', `/v1/containers/${encodeURIComponent(container)}/files/dir`, input),
+      makeDir: (container, input) => send<{ ok: boolean }>('POST', `/v1/containers/${encodeURIComponent(container)}/files/dir`, input),
+      deleteFile: async (container, path) => {
+        await request(`/v1/containers/${encodeURIComponent(container)}/files?path=${encodeURIComponent(path)}`, { method: 'DELETE' });
+      },
+      deletePath: async (container, path) => {
+        await request(`/v1/containers/${encodeURIComponent(container)}/files?path=${encodeURIComponent(path)}`, { method: 'DELETE' });
+      },
+    },
+    serviceVolumes: {
+      list: (serviceId) => get<Array<ServiceVolumeAttachment & { sizeBytes: number; inUse: boolean; sharedWith: number }>>(`/v1/services/${serviceId}/volumes`),
+      create: (serviceId, input) =>
+        send<{ attachment: ServiceVolumeAttachment; deploymentId: number }>('POST', `/v1/services/${serviceId}/volumes`, input),
+      update: (serviceId, attachmentId, input) =>
+        send<{ attachment: ServiceVolumeAttachment; deploymentId: number }>(
+          'PATCH',
+          `/v1/services/${serviceId}/volumes/${attachmentId}`,
+          input,
+        ),
+      remove: async (serviceId, attachmentId) => {
+        await request(`/v1/services/${serviceId}/volumes/${attachmentId}`, { method: 'DELETE' });
+      },
+      repairConfig: (serviceId, input) =>
+        send<{ ok: boolean; deploymentId: number }>('POST', `/v1/services/${serviceId}/volumes/config-repair`, input),
+    },
+  };
+}

package/src/terminal.ts

@@ -0,0 +1,254 @@
+// Terminal sessions over WebSocket (0.15 T6).
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import type {
+  TerminalSessionCreated,
+  TerminalTargetKind,
+} from '@ninedeploy/schemas';
+import { NineDeployError } from './errors.js';
+
+/** Attach subprotocol (protocol v1) and the ticket's subprotocol prefix; mirror `@ninedeploy/schemas`. */
+export const TERMINAL_SUBPROTOCOL = 'ninedeploy.terminal.v1';
+
+export const TERMINAL_TICKET_PREFIX = 'ninedeploy.ticket.';
+
+/** The server closes a socket whose frame exceeds 64 KiB (1009); input is sent in smaller pieces. */
+export const TERMINAL_INPUT_CHUNK_BYTES = 32 * 1024;
+
+/** Input typed before the shell is `ready` is held, up to this many bytes. */
+export const TERMINAL_PENDING_INPUT_MAX = 64 * 1024;
+
+/** What `attachInfo` needs from `terminals.create`'s answer. */
+export type TerminalAttachSource = Pick<TerminalSessionCreated, 'ticket' | 'attachPath'>;
+
+/** A page location, for a client whose `baseUrl` is relative (the dashboard). */
+export interface WebSocketLocation {
+  protocol: string;
+  host: string;
+}
+
+export interface TerminalAttachInfo {
+  url: string;
+  /** `['ninedeploy.terminal.v1', 'ninedeploy.ticket.<ticket>']`: the server selects the first, so the ticket is never echoed. */
+  protocols: string[];
+}
+
+/**
+ * The attach WebSocket URL for `baseUrl` (absolute, or relative to
+ * `location` / `globalThis.location`) and the v1 subprotocols.
+ */
+export function terminalAttachInfo(baseUrl: string, created: TerminalAttachSource, location?: WebSocketLocation): TerminalAttachInfo {
+  if (!/^\/v1\/terminals\/\d+\/attach$/.test(created.attachPath)) {
+    throw new NineDeployError(0, 'invalid_path', `Not a terminal attach path: ${created.attachPath}`);
+  }
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(created.ticket)) {
+    throw new NineDeployError(0, 'invalid_ticket', 'The terminal ticket is malformed');
+  }
+  const base = baseUrl.replace(/\/+$/, '');
+  let url: string;
+  if (/^https?:\/\//i.test(base)) {
+    url = `${base.replace(/^http/i, 'ws')}${created.attachPath}`;
+  } else {
+    const loc = location ?? (globalThis as { location?: WebSocketLocation }).location;
+    if (!loc) throw new NineDeployError(0, 'no_base_url', 'A relative baseUrl needs a page location to build a WebSocket URL');
+    const proto = loc.protocol === 'https:' ? 'wss' : 'ws';
+    url = `${proto}://${loc.host}${base}${created.attachPath}`;
+  }
+  return { url, protocols: [TERMINAL_SUBPROTOCOL, `${TERMINAL_TICKET_PREFIX}${created.ticket}`] };
+}
+
+/** A human sentence for an attach socket's close code. */
+export function terminalCloseMessage(code: number): string {
+  switch (code) {
+    case 1000:
+      return 'The shell exited.';
+    case 1009:
+      return 'A message was too large (over 64 KiB), so the session was closed.';
+    case 4401:
+      return 'The session ticket was invalid or expired. Open a new terminal.';
+    case 4403:
+      return 'Access was refused: the session was revoked, or this page is not a panel origin.';
+    case 4408:
+      return 'The session was closed after being idle too long.';
+    case 4409:
+      return 'The session reached its maximum length.';
+    case 4410:
+      return 'An operator terminated this session.';
+    case 4429:
+      return 'Too many terminals are open. Close one and try again.';
+    case 4502:
+      return 'The target could not be reached.';
+    default:
+      return `The connection was lost (code ${code}).`;
+  }
+}
+
+/** The structural WebSocket the connection drives (browser `WebSocket`, Node's global one, or `ws`). */
+export interface TerminalSocketLike {
+  binaryType: string;
+  readyState: number;
+  send(data: string | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((event: unknown) => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onclose: ((event: { code: number; reason: string }) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+}
+
+export type TerminalSocketFactory = (url: string, protocols: string[]) => TerminalSocketLike;
+
+export interface TerminalReady {
+  sessionId: number;
+  target: { kind: TerminalTargetKind; label: string; serverId: number | null };
+}
+
+export interface TerminalHandlers {
+  /** The shell runs; input typed before this was held and is flushed now. */
+  onReady?: (ready: TerminalReady) => void;
+  /** Shell output. */
+  onData?: (bytes: Uint8Array) => void;
+  /** A server notice (why a session failed, an ignored control message). */
+  onNotice?: (message: string) => void;
+  /** The server's `exit` message: the shell's exit code (null when unknown) and the end reason. */
+  onExit?: (exit: { code: number | null; reason: string }) => void;
+  /** The socket closed; `message` explains the close code. */
+  onClose?: (close: { code: number; reason: string; message: string }) => void;
+}
+
+export interface TerminalConnectOptions {
+  /** Defaults to `globalThis.WebSocket`. */
+  socketFactory?: TerminalSocketFactory;
+  /** For a relative `baseUrl` outside a browser page. */
+  location?: WebSocketLocation;
+  /** Keep-alive ping interval (ms); pings do not reset the idle timeout. 0 disables. Default 30s. */
+  pingIntervalMs?: number;
+}
+
+export interface TerminalConnection {
+  /** True once the server sent `ready`. */
+  readonly ready: boolean;
+  /** Send input (held until `ready`, then sent in frames below the server's cap). */
+  write: (data: string | Uint8Array) => void;
+  /** Resize the terminal (clamped to 10–500 × 5–200; the last size before `ready` is sent on `ready`). */
+  resize: (cols: number, rows: number) => void;
+  close: () => void;
+}
+
+const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, Math.round(n)));
+
+/** Timers and TextEncoder exist wherever the SDK runs; typed structurally (no DOM or Node lib types). */
+const runtime = globalThis as unknown as {
+  setInterval: (fn: () => void, ms: number) => unknown;
+  clearInterval: (handle: unknown) => void;
+  TextEncoder: new () => { encode: (text: string) => Uint8Array };
+};
+
+function defaultSocketFactory(): TerminalSocketFactory {
+  const Ctor = (globalThis as { WebSocket?: new (url: string, protocols: string[]) => TerminalSocketLike }).WebSocket;
+  if (!Ctor) throw new NineDeployError(0, 'no_websocket', 'No WebSocket implementation is available; pass socketFactory');
+  return (url, protocols) => new Ctor(url, protocols);
+}
+
+function toBytes(data: unknown): Uint8Array {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  const view = data as ArrayBufferView;
+  return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+}
+
+/**
+ * Attach to a terminal session over protocol v1 (`ninedeploy.terminal.v1`).
+ *
+ * Binary frames carry input and output; text frames carry the JSON control
+ * messages. Input written before the server's `ready` is held (up to 64 KiB)
+ * and flushed on `ready`, because the server may drop input that arrives
+ * while it is still starting the shell.
+ */
+export function connectTerminal(info: TerminalAttachInfo, handlers: TerminalHandlers = {}, options: TerminalConnectOptions = {}): TerminalConnection {
+  const factory = options.socketFactory ?? defaultSocketFactory();
+  const socket = factory(info.url, info.protocols);
+  socket.binaryType = 'arraybuffer';
+  const encoder = new runtime.TextEncoder();
+  let ready = false;
+  let closed = false;
+  let pending: Uint8Array[] = [];
+  let pendingBytes = 0;
+  let size: { cols: number; rows: number } | null = null;
+  let ping: unknown;
+
+  const sendInput = (bytes: Uint8Array) => {
+    for (let at = 0; at < bytes.length; at += TERMINAL_INPUT_CHUNK_BYTES) {
+      socket.send(bytes.subarray(at, at + TERMINAL_INPUT_CHUNK_BYTES));
+    }
+  };
+  const sendResize = (cols: number, rows: number) => socket.send(JSON.stringify({ t: 'resize', cols, rows }));
+
+  socket.onmessage = (event) => {
+    if (typeof event.data !== 'string') {
+      handlers.onData?.(toBytes(event.data));
+      return;
+    }
+    let msg: { t?: unknown; message?: unknown; code?: unknown; reason?: unknown; sessionId?: unknown; target?: unknown };
+    try {
+      msg = JSON.parse(event.data) as typeof msg;
+    } catch {
+      return;
+    }
+    if (msg.t === 'ready') {
+      ready = true;
+      if (size) sendResize(size.cols, size.rows);
+      const held = pending;
+      pending = [];
+      pendingBytes = 0;
+      for (const bytes of held) sendInput(bytes);
+      handlers.onReady?.({ sessionId: msg.sessionId as number, target: msg.target as TerminalReady['target'] });
+      const every = options.pingIntervalMs ?? 30_000;
+      if (every > 0) {
+        ping = runtime.setInterval(() => {
+          if (!closed) socket.send(JSON.stringify({ t: 'ping' }));
+        }, every);
+      }
+    } else if (msg.t === 'notice') {
+      handlers.onNotice?.(String(msg.message));
+    } else if (msg.t === 'exit') {
+      handlers.onExit?.({ code: typeof msg.code === 'number' ? msg.code : null, reason: String(msg.reason) });
+    }
+  };
+  socket.onclose = (event) => {
+    closed = true;
+    ready = false;
+    runtime.clearInterval(ping);
+    handlers.onClose?.({ code: event.code, reason: event.reason, message: terminalCloseMessage(event.code) });
+  };
+  socket.onerror = () => {
+    /* the close event follows and carries the code */
+  };
+
+  return {
+    get ready() {
+      return ready;
+    },
+    write: (data) => {
+      if (closed) return;
+      const bytes = typeof data === 'string' ? encoder.encode(data) : data;
+      if (bytes.length === 0) return;
+      if (ready) {
+        sendInput(bytes);
+        return;
+      }
+      if (pendingBytes + bytes.length > TERMINAL_PENDING_INPUT_MAX) return;
+      pending.push(bytes);
+      pendingBytes += bytes.length;
+    },
+    resize: (cols, rows) => {
+      size = { cols: clamp(cols, 10, 500), rows: clamp(rows, 5, 200) };
+      if (ready && !closed) sendResize(size.cols, size.rows);
+    },
+    close: () => {
+      if (closed) return;
+      closed = true;
+      runtime.clearInterval(ping);
+      socket.close(1000, 'client closed');
+    },
+  };
+}

package/src/transport.ts

@@ -0,0 +1,154 @@
+// HTTP request core shared by every resource module.
+// Split out of the former single-file SDK entry (src/index.ts); the public
+// surface is re-exported unchanged from there.
+import { NineDeployError } from './errors.js';
+
+/**
+ * Minimal structural fetch type so the SDK is isomorphic (browser + Node)
+ * without pulling in DOM lib types. Both `globalThis.fetch` implementations
+ * satisfy this shape.
+ */
+export type FetchLike = (input: string, init: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    credentials?: 'omit' | 'same-origin' | 'include';
+  }) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    /** Optional so minimal fetch stand-ins stay assignable; a real fetch has it (F1010). */
+    headers?: { get(name: string): string | null };
+  }>
+
+export interface NineDeployClientOptions {
+  /** Base URL of the NineDeploy API, e.g. http://localhost:3000. */
+  baseUrl: string;
+  /** Returns the current access token (or bearer credential). */
+  getToken?: () => string | undefined | null;
+  /**
+   * Per-request timeout in milliseconds. A stalled backend must not hang
+   * callers forever (worst in CI, where nothing is interactive to Ctrl-C).
+   * Defaults to 30_000; pass `0` to disable entirely.
+   */
+  timeoutMs?: number;
+  /** Custom fetch implementation (defaults to globalThis.fetch). */
+  fetch?: FetchLike;
+}
+
+export interface RequestInit {
+  method?: string;
+  credentials?: 'omit' | 'same-origin' | 'include';
+  headers?: Record<string, string>;
+  body?: unknown;
+  /**
+   * Propagated to fetch as-is. Typed structurally: the SDK compiles without
+   * DOM lib types, and only `AbortSignal.timeout()` ever produces one here.
+   */
+  signal?: unknown;
+  /** 0.14: a binary body, sent as-is (`application/octet-stream`). */
+  raw?: Uint8Array;
+  /** 0.14: keep a refusal's top-level `errors` / `warnings` as the error's `details`. */
+  findings?: boolean;
+}
+
+const NO_FETCH = (): Promise<never> =>
+  Promise.reject(new NineDeployError(0, 'no_fetch', 'No fetch implementation is available'));
+
+/** The request core every resource module calls through. */
+export interface Transport {
+  baseUrl: string;
+  requestWithHeaders<T>(path: string, init?: RequestInit, minTimeoutMs?: number): Promise<{ data: T; header: (name: string) => string | null }>;
+  request<T>(path: string, init?: RequestInit, minTimeoutMs?: number): Promise<T>;
+  get<T>(path: string): Promise<T>;
+  send<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+
+export function createTransport(opts: NineDeployClientOptions): Transport {
+  const baseUrl = opts.baseUrl.replace(/\/$/, '');
+  const fetchImpl: FetchLike = opts.fetch ?? ((globalThis as { fetch?: FetchLike }).fetch ?? NO_FETCH);
+  /** Default per-request budget when the caller does not configure one. */
+  const DEFAULT_TIMEOUT_MS = 30_000;
+
+  /** A call's parsed body plus read access to its response headers (F1010). */
+  async function requestWithHeaders<T>(
+    path: string,
+    init: RequestInit = {},
+    minTimeoutMs?: number,
+  ): Promise<{ data: T; header: (name: string) => string | null }> {
+    const token = opts.getToken?.();
+    const headers: Record<string, string> = { ...(init.headers ?? {}) };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+    if (init.body !== undefined && headers['Content-Type'] === undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    const body = init.body === undefined ? undefined : JSON.stringify(init.body);
+    const configured = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // A long-running call (image pull) may widen the budget, never narrow it;
+    // `0` (timeouts disabled) stays disabled.
+    const timeoutMs = configured > 0 && minTimeoutMs !== undefined ? Math.max(configured, minTimeoutMs) : configured;
+    // AbortSignal.timeout exists everywhere the SDK runs (Node 17.3+, all
+    // modern browsers); it is resolved off globalThis and attached opaquely —
+    // FetchLike's shape stays untouched (widening it with `signal: unknown`
+    // breaks assigning a real `typeof fetch` at the call sites).
+    const out: { method?: string; headers?: Record<string, string>; body?: string; credentials?: 'omit' | 'same-origin' | 'include' } = {
+      method: init.method ?? 'GET',
+      headers,
+      body,
+    };
+    if (init.credentials !== undefined) out.credentials = init.credentials;
+    if (init.raw !== undefined) {
+      // Attached opaquely, like the signal: FetchLike's `body` stays `string`.
+      headers['Content-Type'] = 'application/octet-stream';
+      (out as { body?: unknown }).body = init.raw;
+    }
+    if (timeoutMs > 0) {
+      const abort = (globalThis as { AbortSignal?: { timeout: (ms: number) => unknown } }).AbortSignal;
+      if (abort) (out as { signal?: unknown }).signal = abort.timeout(timeoutMs);
+    }
+
+    const res = await fetchImpl(`${baseUrl}${path}`, out);
+    const header = (name: string): string | null => (typeof res.headers?.get === 'function' ? res.headers.get(name) : null);
+    const text = await res.text();
+    // Guard the parse: proxies (HTML 502 pages, empty bodies) must surface as a
+    // typed error, not an opaque SyntaxError.
+    let parsed: unknown;
+    try {
+      parsed = text ? (JSON.parse(text) as unknown) : undefined;
+    } catch {
+      parsed = undefined;
+    }
+
+    if (!res.ok) {
+      if (parsed === undefined) throw new NineDeployError(res.status, 'http_error', `Request failed (${res.status})`);
+      const failure = NineDeployError.fromBody(res.status, parsed);
+      const findings = parsed as { errors?: unknown; warnings?: unknown };
+      if (init.findings && Array.isArray(findings.errors)) {
+        throw new NineDeployError(failure.status, failure.code, failure.message, {
+          errors: findings.errors,
+          warnings: Array.isArray(findings.warnings) ? findings.warnings : [],
+        });
+      }
+      throw failure;
+    }
+    // An ok response with an empty/unparseable body (204s, HTML pages from a
+    // misconfigured proxy) must never resolve to `undefined` — query functions
+    // built on this client would crash TanStack Query ("Query data cannot be
+    // undefined"). Empty 2xx bodies resolve to {}; non-JSON bodies surface as
+    // a typed error so callers see the real problem instead of a crash.
+    if (parsed === undefined) {
+      if (text === '') return { data: {} as T, header };
+      throw new NineDeployError(res.status, 'invalid_response', `Expected JSON but received a non-JSON body (status ${res.status})`);
+    }
+    return { data: parsed as T, header };
+  }
+
+  async function request<T>(path: string, init: RequestInit = {}, minTimeoutMs?: number): Promise<T> {
+    return (await requestWithHeaders<T>(path, init, minTimeoutMs)).data;
+  }
+
+  const get = <T>(path: string) => request<T>(path);
+  const send = <T>(method: string, path: string, body?: unknown) => request<T>(path, { method, body });
+
+  return { baseUrl, requestWithHeaders, request, get, send };
+}