@horka/app-forge 0.1.0

package/templates/packs/ts-sdk/src/clients/AuthClient.ts

@@ -0,0 +1,168 @@
+import { ApiError } from '../errors/ApiError';
+import type { HttpTransport } from '../core/HttpClient';
+import type { SDKContext } from '../core/SDKContext';
+import { noopLogger, type SDKLogger } from '../core/Logger';
+import { withTimeout } from '../core/withTimeout';
+import type { HttpMethod, TokenPair } from '../types/index';
+
+const ACCESS_TOKEN_KEY = 'access_token';
+const REFRESH_TOKEN_KEY = 'refresh_token';
+const DEFAULT_REFRESH_PATH = '/auth/refresh';
+const DEFAULT_REFRESH_TIMEOUT_MS = 10_000;
+
+export interface AuthClientOptions {
+  /** Refresh endpoint path. Default: `/auth/refresh`. */
+  refreshPath?: string;
+  /** Upper bound on how long any request may wait for a refresh. Default: 10s. */
+  refreshTimeoutMs?: number;
+  logger?: SDKLogger;
+}
+
+/**
+ * Secure-request use case with SINGLE-FLIGHT token refresh (SDK_CONTRACT.md §3).
+ *
+ * Refresh tokens are rotating and single-use: when N concurrent requests hit 401,
+ * exactly ONE refresh call may go out — the first failure starts it, every other
+ * waiter joins the same inflight promise. Without this, N−1 refreshes burn an
+ * already-rotated token and randomly log users out (a real production bug; the
+ * regression test in tests/singleFlight.test.ts is non-negotiable).
+ *
+ * Invariants — do not "simplify" any of these away:
+ * - one shared inflight promise; latecomers await it
+ * - the wait is bounded (withTimeout) — waiters reject, they never hang
+ * - the original request is retried exactly ONCE after a successful refresh
+ * - every waiter is failed on any refresh failure (a half-authenticated session is worse
+ *   than a clean error), BUT tokens are cleared ONLY on a real auth rejection (401 /
+ *   invalid_grant). A transport failure (offline, DNS, refused, timeout, 5xx) means the
+ *   refresh never reached a verdict — clearing tokens there forces a gratuitous logout on
+ *   a session that may still be valid. Network failures propagate; the session survives.
+ * - the refresh call uses the raw transport, never request() (no recursion on 401)
+ */
+export class AuthClient {
+  private refreshing: Promise<void> | null = null;
+  private readonly refreshPath: string;
+  private readonly refreshTimeoutMs: number;
+  private readonly logger: SDKLogger;
+
+  constructor(
+    private readonly http: HttpTransport,
+    private readonly context: SDKContext,
+    options: AuthClientOptions = {},
+  ) {
+    this.refreshPath = options.refreshPath ?? DEFAULT_REFRESH_PATH;
+    this.refreshTimeoutMs = options.refreshTimeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS;
+    this.logger = options.logger ?? noopLogger;
+  }
+
+  /** Wire the tokens obtained by the consumer's login flow into the SDK. */
+  setTokens(tokens: TokenPair): void {
+    this.context.setCookie(ACCESS_TOKEN_KEY, tokens.accessToken);
+    this.context.setCookie(REFRESH_TOKEN_KEY, tokens.refreshToken);
+  }
+
+  clearTokens(): void {
+    this.context.removeCookie(ACCESS_TOKEN_KEY);
+    this.context.removeCookie(REFRESH_TOKEN_KEY);
+  }
+
+  getAccessToken(): string | null {
+    return this.context.getCookie(ACCESS_TOKEN_KEY);
+  }
+
+  /** An authenticated request: 401 → join/start the single-flight refresh → retry once. */
+  async request<T>(method: HttpMethod, path: string, body?: unknown): Promise<T> {
+    const attempt = async (): Promise<T> => {
+      const token = this.getAccessToken();
+      if (!token) {
+        throw new ApiError({
+          code: 401,
+          name: 'MissingToken',
+          description: 'No access token available — authenticate first',
+          statusCode: 401,
+        });
+      }
+      return this.http.request<T>(method, path, { token, body });
+    };
+
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!AuthClient.isUnauthorized(error)) throw error;
+      this.logger.debug('401 received — joining token refresh', { path });
+      await this.refreshTokens();
+      return attempt(); // retry exactly ONCE with the refreshed token
+    }
+  }
+
+  /** Single-flight: all concurrent 401s share one inflight refresh promise. */
+  private refreshTokens(): Promise<void> {
+    if (!this.refreshing) {
+      this.refreshing = this.doRefresh().finally(() => {
+        this.refreshing = null;
+      });
+    }
+    return this.refreshing;
+  }
+
+  private async doRefresh(): Promise<void> {
+    const refreshToken = this.context.getCookie(REFRESH_TOKEN_KEY);
+    if (!refreshToken) {
+      this.clearTokens();
+      throw new ApiError({
+        code: 401,
+        name: 'MissingRefreshToken',
+        description: 'No refresh token available — cannot refresh the session',
+        statusCode: 401,
+      });
+    }
+
+    try {
+      const pair = await withTimeout(
+        // Raw transport on purpose: a 401 from the refresh endpoint must not recurse.
+        this.http.request<TokenPair>('POST', this.refreshPath, { body: { refreshToken } }),
+        this.refreshTimeoutMs,
+        () =>
+          new ApiError({
+            code: 408,
+            name: 'RefreshTimeout',
+            description: `Token refresh timed out after ${this.refreshTimeoutMs}ms`,
+            statusCode: 408,
+          }),
+      );
+      this.setTokens(pair);
+      this.logger.debug('token refresh succeeded');
+    } catch (error) {
+      // Fail every waiter regardless — a half-authenticated session is worse than a clean
+      // error. But only DROP the session when the server actually rejected the refresh token
+      // (401 / invalid_grant). A transport failure (offline/DNS/refused/timeout/5xx) never
+      // reached a verdict: clearing here would log the user out over a flaky network.
+      if (AuthClient.isAuthRejection(error)) {
+        this.clearTokens();
+        this.logger.error('token refresh rejected — tokens cleared');
+      } else {
+        this.logger.error('token refresh failed (transport) — tokens kept');
+      }
+      throw error;
+    }
+  }
+
+  private static isUnauthorized(error: unknown): boolean {
+    return error instanceof ApiError && error.statusCode === 401;
+  }
+
+  /**
+   * True only for a genuine auth rejection from the refresh endpoint — a 401, or a 400
+   * carrying the OAuth `invalid_grant` code. Timeouts (RefreshTimeout, 408), 5xx and raw
+   * network errors are transport failures, NOT a verdict on the refresh token.
+   */
+  private static isAuthRejection(error: unknown): boolean {
+    if (!(error instanceof ApiError)) return false;
+    if (error.statusCode === 401) return true;
+    if (error.statusCode === 400) {
+      // OAuth refresh rejection: the wire body's name is `invalid_grant`, or the raw body
+      // mentions it (servers vary). A plain 400 without that signal is NOT an auth verdict.
+      return error.errorName === 'invalid_grant' || /invalid_grant/i.test(error.rawMessage ?? '');
+    }
+    return false;
+  }
+}

package/templates/packs/ts-sdk/src/core/HttpClient.ts

@@ -0,0 +1,85 @@
+import { ApiError } from '../errors/ApiError';
+import type { HttpMethod } from '../types/index';
+import { noopLogger, type SDKLogger } from './Logger';
+
+export interface RequestOptions {
+  /** Bearer token added as the Authorization header when present. */
+  token?: string | null;
+  /** JSON-serialized unless it is FormData. */
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Transport port. Clients and use cases depend on THIS interface, never on
+ * `fetch` — tests stub it, alternative transports implement it.
+ */
+export interface HttpTransport {
+  request<T>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+}
+
+export interface HttpClientOptions {
+  baseURL: string;
+  /** Injected for tests/polyfills; defaults to the global fetch (Node 20+/browsers). */
+  fetchFn?: typeof fetch;
+  logger?: SDKLogger;
+}
+
+/**
+ * The fetch adapter (L2). Single responsibility: send the request, normalize
+ * every non-2xx response into an ApiError. No retries, no auth logic — that
+ * lives in clients/AuthClient.ts.
+ */
+export class HttpClient implements HttpTransport {
+  private readonly baseURL: string;
+  private readonly fetchFn: typeof fetch;
+  private readonly logger: SDKLogger;
+
+  constructor(options: HttpClientOptions) {
+    this.baseURL = options.baseURL.replace(/\/+$/, '');
+    this.fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+    this.logger = options.logger ?? noopLogger;
+  }
+
+  async request<T>(method: HttpMethod, path: string, options: RequestOptions = {}): Promise<T> {
+    const headers: Record<string, string> = { Accept: 'application/json', ...options.headers };
+    if (options.token) headers['Authorization'] = `Bearer ${options.token}`;
+
+    let body: BodyInit | undefined;
+    if (options.body !== undefined) {
+      if (options.body instanceof FormData) {
+        body = options.body;
+      } else {
+        headers['Content-Type'] = 'application/json';
+        body = JSON.stringify(options.body);
+      }
+    }
+
+    // Method + path only — never headers, never token material (CONVENTIONS_TS.md §4).
+    this.logger.debug('http request', { method, path });
+
+    const response = await this.fetchFn(`${this.baseURL}${path}`, { method, headers, body });
+    if (!response.ok) {
+      throw ApiError.fromResponse(response.status, await response.text());
+    }
+
+    // No-body responses: 204/205, or any 2xx whose body is empty or not JSON. Calling
+    // response.json() on those throws a raw SyntaxError that escapes the ApiError contract
+    // (consumers expect either T or an ApiError, never a SyntaxError). Read the text once,
+    // return undefined when there is nothing to parse, parse only genuine JSON.
+    if (response.status === 204 || response.status === 205) return undefined as T;
+
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    if (text.length === 0) return undefined as T;
+    if (!contentType.includes('json')) return undefined as T;
+
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      // A JSON content-type with an unparseable body is a malformed success response;
+      // surface it as a typed ApiError instead of leaking the SyntaxError.
+      throw ApiError.fromResponse(response.status, text);
+    }
+  }
+}

package/templates/packs/ts-sdk/src/core/Logger.ts

@@ -0,0 +1,27 @@
+/**
+ * Ops port — injected logger, silent by default (SDK_CONTRACT.md §5).
+ *
+ * Zero direct console calls anywhere in src/: the consumer owns the output and the switch.
+ * NEVER log token values, Authorization headers, or token-presence booleans —
+ * a production team once mapped its whole auth topology into every consumer's
+ * devtools that way. Log method + path, nothing from headers.
+ */
+
+export interface SDKLogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+export const noopLogger: SDKLogger = {
+  debug: () => {},
+  error: () => {},
+};
+
+/** Gate `debug()` behind the consumer's `debug` flag; errors always pass through. */
+export function gateDebug(logger: SDKLogger, debug: boolean): SDKLogger {
+  if (debug) return logger;
+  return {
+    debug: () => {},
+    error: (message, meta) => logger.error(message, meta),
+  };
+}

package/templates/packs/ts-sdk/src/core/SDKContext.ts

@@ -0,0 +1,40 @@
+/**
+ * Storage port — the SDK never touches `document.cookie` or framework internals
+ * directly (SDK_CONTRACT.md §3, "Storage is an injected port").
+ *
+ * The skeleton ships the in-memory adapter only (tests, CLI, server-side jobs).
+ * Adding a browser or SSR adapter is a recorded decision: read the token-storage
+ * tradeoff table in SDK_CONTRACT.md §3 and write the choice + mitigations into
+ * `.claude/memory/DECISIONS.md` — never inherit a default silently.
+ */
+
+export interface CookieOptions {
+  path?: string;
+  maxAge?: number;
+  domain?: string;
+  secure?: boolean;
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+
+export interface SDKContext {
+  getCookie(name: string): string | null;
+  setCookie(name: string, value: string, options?: CookieOptions): void;
+  removeCookie(name: string): void;
+}
+
+/**
+ * In-memory adapter: process-local, non-persistent.
+ * The default context — and the reference implementation for any other adapter.
+ */
+export function createMemoryContext(): SDKContext {
+  const store = new Map<string, string>();
+  return {
+    getCookie: (name) => store.get(name) ?? null,
+    setCookie: (name, value) => {
+      store.set(name, value);
+    },
+    removeCookie: (name) => {
+      store.delete(name);
+    },
+  };
+}

package/templates/packs/ts-sdk/src/core/withTimeout.ts

@@ -0,0 +1,19 @@
+/**
+ * Bound a promise with a timeout — used to guarantee that token-refresh waiters
+ * are never parked forever (SDK_CONTRACT.md §3: "always bound the wait").
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, makeError: () => Error): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(makeError()), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      },
+    );
+  });
+}

package/templates/packs/ts-sdk/src/errors/ApiError.ts

@@ -0,0 +1,93 @@
+import type { ApiErrorBody } from '../types/index';
+
+interface ApiErrorDetails extends ApiErrorBody {
+  statusCode: number;
+  rawMessage?: string;
+}
+
+const STATUS_NAMES: Record<number, string> = {
+  400: 'BadRequest',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'NotFound',
+  408: 'RequestTimeout',
+  409: 'Conflict',
+  422: 'UnprocessableEntity',
+  429: 'TooManyRequests',
+  500: 'InternalServerError',
+  502: 'BadGateway',
+  503: 'ServiceUnavailable',
+  504: 'GatewayTimeout',
+};
+
+/**
+ * The ONE error type every non-2xx response becomes (SDK_CONTRACT.md §2).
+ * The transport throws it; consumers map `statusCode` to UX in one shared handler.
+ * Nothing in this SDK ever swallows a status code or re-parses a response body.
+ */
+export class ApiError extends Error {
+  /** Application-level error code from the wire body (falls back to the HTTP status). */
+  public readonly code: number;
+  /** Machine-readable error name (`Unauthorized`, `Conflict`, …). */
+  public readonly errorName: string;
+  /** The HTTP status code of the response. */
+  public readonly statusCode: number;
+  /** The raw response text, for diagnostics only — never re-parse it downstream. */
+  public readonly rawMessage?: string;
+
+  constructor(details: ApiErrorDetails) {
+    super(details.description);
+    this.name = 'ApiError';
+    this.code = details.code;
+    this.errorName = details.name;
+    this.statusCode = details.statusCode;
+    this.rawMessage = details.rawMessage;
+  }
+
+  /**
+   * Normalize a non-2xx response into an ApiError:
+   * 1. try to parse the body as the wire contract `{ code, name, description }`;
+   * 2. on shape mismatch or parse failure, build a standard error from the status code.
+   */
+  static fromResponse(statusCode: number, responseText: string): ApiError {
+    try {
+      const parsed: unknown = JSON.parse(responseText);
+      if (ApiError.isWireBody(parsed)) {
+        return new ApiError({ ...parsed, statusCode, rawMessage: responseText });
+      }
+      return ApiError.fromStatus(statusCode, responseText);
+    } catch {
+      return ApiError.fromStatus(statusCode, responseText);
+    }
+  }
+
+  private static isWireBody(value: unknown): value is ApiErrorBody {
+    if (typeof value !== 'object' || value === null) return false;
+    const body = value as Record<string, unknown>;
+    return (
+      typeof body['code'] === 'number' &&
+      typeof body['name'] === 'string' &&
+      typeof body['description'] === 'string'
+    );
+  }
+
+  private static fromStatus(statusCode: number, message: string): ApiError {
+    const name = STATUS_NAMES[statusCode] ?? 'UnknownError';
+    return new ApiError({
+      code: statusCode,
+      name,
+      description: `${statusCode} ${name}${message ? ` - ${message}` : ''}`,
+      statusCode,
+      rawMessage: message,
+    });
+  }
+
+  toJSON(): ApiErrorBody & { statusCode: number } {
+    return {
+      code: this.code,
+      name: this.errorName,
+      description: this.message,
+      statusCode: this.statusCode,
+    };
+  }
+}

package/templates/packs/ts-sdk/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Composition root (L5) — the ONLY file that constructs adapters and wires
+ * transport → auth → resource clients. It re-exports the entire public surface;
+ * anything not exported here (or from ./types) does not exist for consumers.
+ */
+import { AuthClient } from './clients/AuthClient';
+import { HttpClient } from './core/HttpClient';
+import { gateDebug, noopLogger, type SDKLogger } from './core/Logger';
+import { createMemoryContext, type SDKContext } from './core/SDKContext';
+
+export interface SDKOptions {
+  /** API origin, e.g. `https://api.example.com` (no trailing slash needed). */
+  baseURL: string;
+  /** Storage adapter. Defaults to the in-memory context — see SDKContext.ts. */
+  context?: SDKContext;
+  /** Consumer-owned logger; silent no-op by default. */
+  logger?: SDKLogger;
+  /** Enables logger.debug output. The CONSUMER owns this switch. */
+  debug?: boolean;
+  /** Injected fetch for tests/polyfills. */
+  fetchFn?: typeof fetch;
+  refreshPath?: string;
+  refreshTimeoutMs?: number;
+}
+
+export class {{PROJECT_NAME}}Sdk {
+  /** Raw transport — for public (unauthenticated) endpoints. */
+  readonly http: HttpClient;
+  /** Authenticated requests with single-flight token refresh. */
+  readonly auth: AuthClient;
+  // Add resource clients as the API grows (docs-architecture/ARCHITECTURE.md §4):
+  //   readonly projects: ProjectClient;
+
+  constructor(options: SDKOptions) {
+    const logger = gateDebug(options.logger ?? noopLogger, options.debug ?? false);
+    const context = options.context ?? createMemoryContext();
+    this.http = new HttpClient({ baseURL: options.baseURL, fetchFn: options.fetchFn, logger });
+    this.auth = new AuthClient(this.http, context, {
+      logger,
+      refreshPath: options.refreshPath,
+      refreshTimeoutMs: options.refreshTimeoutMs,
+    });
+    //   this.projects = new ProjectClient(this.auth);
+  }
+}
+
+export function createSdk(options: SDKOptions): {{PROJECT_NAME}}Sdk {
+  return new {{PROJECT_NAME}}Sdk(options);
+}
+
+// ── Public surface (keep scripts/verify-dist.mjs in sync) ──────────────────
+export { ApiError } from './errors/ApiError';
+export { AuthClient, type AuthClientOptions } from './clients/AuthClient';
+export {
+  HttpClient,
+  type HttpTransport,
+  type RequestOptions,
+  type HttpClientOptions,
+} from './core/HttpClient';
+export { createMemoryContext, type SDKContext, type CookieOptions } from './core/SDKContext';
+export { noopLogger, type SDKLogger } from './core/Logger';
+export type { ApiErrorBody, HttpMethod, TokenPair } from './types/index';

package/templates/packs/ts-sdk/src/types/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Wire types — the shapes that cross the network, mirroring the backend DTOs.
+ *
+ * RULES (docs-architecture/ARCHITECTURE.md §2):
+ * - This module imports NOTHING else in the package (it is the SDK's L0).
+ * - Declarations only: interfaces, type aliases, string-literal unions. No runtime code.
+ * - Plain .ts, never .d.ts (declaration generators skip .d.ts sources silently).
+ *
+ * Consumers reach these through the types-only subpath:
+ *   import type { TokenPair } from '{{BUNDLE_ID}}/types'
+ */
+
+/** HTTP methods the transport accepts. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/** Auth token pair returned by the refresh endpoint. Refresh tokens are single-use. */
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+/**
+ * The frozen wire shape of an API error body.
+ * Renaming a field here is a breaking change in TWO repos (SDK_CONTRACT.md §2).
+ */
+export interface ApiErrorBody {
+  code: number;
+  name: string;
+  description: string;
+}
+
+// Add resource wire types below (one file per resource once a resource has >1 type),
+// and re-export them from this index so they ship through "./types".

package/templates/packs/ts-sdk/tests/apiError.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect } from 'vitest';
+import { ApiError } from '../src/index';
+
+describe('ApiError.fromResponse — error normalization (SDK_CONTRACT.md §2)', () => {
+  test('parses the wire contract { code, name, description }', () => {
+    const body = JSON.stringify({ code: 4091, name: 'TeamAlreadyExists', description: 'A team with this name exists' });
+
+    const error = ApiError.fromResponse(409, body);
+
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error).toBeInstanceOf(Error);
+    expect(error.name).toBe('ApiError');
+    expect(error.code).toBe(4091);
+    expect(error.errorName).toBe('TeamAlreadyExists');
+    expect(error.message).toBe('A team with this name exists');
+    expect(error.statusCode).toBe(409);
+    expect(error.rawMessage).toBe(body);
+  });
+
+  test('falls back to a standard error when the body is not JSON', () => {
+    const error = ApiError.fromResponse(500, '<html>Internal blowup</html>');
+
+    expect(error.statusCode).toBe(500);
+    expect(error.code).toBe(500);
+    expect(error.errorName).toBe('InternalServerError');
+    expect(error.message).toContain('500');
+    expect(error.rawMessage).toBe('<html>Internal blowup</html>');
+  });
+
+  test('falls back when the JSON does not match the wire shape', () => {
+    const error = ApiError.fromResponse(400, JSON.stringify({ message: 'wrong shape' }));
+
+    expect(error.errorName).toBe('BadRequest');
+    expect(error.code).toBe(400);
+    expect(error.statusCode).toBe(400);
+  });
+
+  test('unknown status codes still normalize', () => {
+    const error = ApiError.fromResponse(418, 'teapot');
+
+    expect(error.errorName).toBe('UnknownError');
+    expect(error.statusCode).toBe(418);
+  });
+
+  test('toJSON round-trips the frozen wire shape', () => {
+    const error = ApiError.fromResponse(
+      403,
+      JSON.stringify({ code: 4030, name: 'Forbidden', description: 'No access to this resource' }),
+    );
+
+    expect(error.toJSON()).toEqual({
+      code: 4030,
+      name: 'Forbidden',
+      description: 'No access to this resource',
+      statusCode: 403,
+    });
+  });
+});

package/templates/packs/ts-sdk/tests/httpClient.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from 'vitest';
+import { ApiError, HttpClient } from '../src/index';
+
+/**
+ * Transport adapter tests (CONVENTIONS_TS.md §7 — the one place a fake `fetch` is allowed).
+ *
+ * Pins the no-body contract: a 2xx with an empty or non-JSON body must resolve to `undefined`,
+ * never throw a raw SyntaxError from response.json() — that would escape the ApiError contract
+ * (consumers expect either T or an ApiError, never a SyntaxError).
+ */
+
+function fetchReturning(status: number, body: string, contentType?: string): typeof fetch {
+  const headers = new Headers();
+  if (contentType) headers.set('content-type', contentType);
+  return (async () => new Response(body.length ? body : null, { status, headers })) as unknown as typeof fetch;
+}
+
+describe('HttpClient — no-body success responses', () => {
+  test('204 resolves to undefined', async () => {
+    const http = new HttpClient({ baseURL: 'https://api.test', fetchFn: fetchReturning(204, '') });
+    await expect(http.request('DELETE', '/items/1')).resolves.toBeUndefined();
+  });
+
+  test('200 with an empty body resolves to undefined (no SyntaxError)', async () => {
+    const http = new HttpClient({ baseURL: 'https://api.test', fetchFn: fetchReturning(200, '') });
+    await expect(http.request('POST', '/items/1/touch')).resolves.toBeUndefined();
+  });
+
+  test('200 with a non-JSON content-type resolves to undefined', async () => {
+    const http = new HttpClient({
+      baseURL: 'https://api.test',
+      fetchFn: fetchReturning(200, 'OK', 'text/plain'),
+    });
+    await expect(http.request('GET', '/ping')).resolves.toBeUndefined();
+  });
+
+  test('200 with a JSON body still parses normally', async () => {
+    const http = new HttpClient({
+      baseURL: 'https://api.test',
+      fetchFn: fetchReturning(200, JSON.stringify({ id: 'x', name: 'First' }), 'application/json'),
+    });
+    await expect(http.request('GET', '/items/x')).resolves.toEqual({ id: 'x', name: 'First' });
+  });
+
+  test('a JSON content-type with a malformed body surfaces a typed ApiError, not a SyntaxError', async () => {
+    const http = new HttpClient({
+      baseURL: 'https://api.test',
+      fetchFn: fetchReturning(200, '{ not json', 'application/json'),
+    });
+    await expect(http.request('GET', '/items/x')).rejects.toBeInstanceOf(ApiError);
+  });
+
+  test('a non-2xx response still throws an ApiError', async () => {
+    const http = new HttpClient({
+      baseURL: 'https://api.test',
+      fetchFn: fetchReturning(409, JSON.stringify({ code: 4090, name: 'Conflict', description: 'exists' }), 'application/json'),
+    });
+    await expect(http.request('POST', '/items')).rejects.toMatchObject({ statusCode: 409, errorName: 'Conflict' });
+  });
+});