feat: RFC 9457 problem+json parsing on HTTPError

When a server emits `Content-Type: application/problem+json` (RFC 9457,
formerly RFC 7807), HTTPError now exposes the parsed shape on
`err.problem`:

  type    URI ref identifying the problem type
  title   short summary
  status  HTTP status (echoed)
  detail  specific occurrence detail
  instance URI ref for this occurrence
  ...     extension fields preserved per spec

The error message also surfaces problem.detail (or title fallback) so
console output is immediately useful:

  HTTPError: Request failed with status 402 Payment Required: Your balance is $0.00.

ProblemDetails type re-exported from the root entry. Spring 6, .NET,
Cloudflare 1xxx errors all emit this format — no major JS HTTP client
parses it natively, so consumers had to reach for `error.data` and
manually inspect content-type. Now they don't.

Audit pass 41 (test/problem-details.test.ts, 6 tests):
  Full shape parsing incl. extension fields, message includes detail,
  title fallback, non-problem content-type leaves problem undefined,
  charset parameter handled, ProblemDetails type reachable from root.

Suite: 376 / 376 (was 370). Lint+typecheck+build clean. Dist 104 kB.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/errors/http.ts

@@ -1,19 +1,63 @@
 import { MisinaError } from "./base.ts"
 
+/**
+ * RFC 9457 problem details (formerly RFC 7807). Servers signal application
+ * errors with `Content-Type: application/problem+json` and this shape.
+ */
+export interface ProblemDetails {
+  /** URI reference identifying the problem type. Default `"about:blank"`. */
+  type?: string
+  /** Short, human-readable summary. */
+  title?: string
+  /** HTTP status code (echoed). */
+  status?: number
+  /** Specific occurrence detail. */
+  detail?: string
+  /** URI reference identifying the specific occurrence. */
+  instance?: string
+  /** Custom extension fields are allowed by the spec. */
+  [key: string]: unknown
+}
+
 export class HTTPError<T = unknown> extends MisinaError {
   override readonly name = "HTTPError"
   readonly status: number
   readonly statusText: string
   readonly response: Response
   readonly request: Request
   readonly data: T
+  /**
+   * Parsed RFC 9457 problem details — present when the response had
+   * `Content-Type: application/problem+json` and a JSON body. `undefined`
+   * otherwise.
+   */
+  readonly problem: ProblemDetails | undefined
 
   constructor(response: Response, request: Request, data: T) {
-    super(`Request failed with status ${response.status} ${response.statusText}`)
+    const problem = extractProblem(response, data)
+    super(buildMessage(response, problem))
     this.status = response.status
     this.statusText = response.statusText
     this.response = response
     this.request = request
     this.data = data
+    this.problem = problem
   }
 }
+
+function extractProblem(response: Response, data: unknown): ProblemDetails | undefined {
+  const ct = response.headers.get("content-type") ?? ""
+  // Match application/problem+json (RFC 9457) and any vendor variant ending
+  // in +problem+json (rare but legal per RFC 6839 structured-syntax suffix).
+  if (!/^application\/problem\+json(;.*)?$/i.test(ct)) return undefined
+  if (!data || typeof data !== "object") return undefined
+  return data as ProblemDetails
+}
+
+function buildMessage(response: Response, problem: ProblemDetails | undefined): string {
+  const base = `Request failed with status ${response.status} ${response.statusText}`
+  if (!problem) return base
+  // Prefer detail, fall back to title — both are spec-encouraged.
+  const blurb = problem.detail ?? problem.title
+  return blurb ? `${base}: ${blurb}` : base
+}

src/errors/index.ts

@@ -1,5 +1,5 @@
 export { MisinaError } from "./base.ts"
-export { HTTPError } from "./http.ts"
+export { HTTPError, type ProblemDetails } from "./http.ts"
 export { isRawNetworkError, NetworkError } from "./network.ts"
 export { TimeoutError } from "./timeout.ts"
 

src/index.ts

@@ -27,6 +27,7 @@ export {
   isTimeoutError,
   MisinaError,
   NetworkError,
+  type ProblemDetails,
   TimeoutError,
 } from "./errors/index.ts"
 

test/problem-details.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest"
+import { createMisina, HTTPError, type ProblemDetails } from "../src/index.ts"
+
+describe("RFC 9457 — problem+json on HTTPError", () => {
+  it("parses application/problem+json into err.problem", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(
+          JSON.stringify({
+            type: "https://example.test/errors/insufficient-funds",
+            title: "Insufficient Funds",
+            status: 402,
+            detail: "Your balance is $0.00.",
+            instance: "/transactions/123",
+            balance: 0,
+          }),
+          {
+            status: 402,
+            headers: { "content-type": "application/problem+json" },
+          },
+        ),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const err = (await m.post("https://api.test/buy", { item: 1 }).catch((e) => e)) as HTTPError
+    expect(err).toBeInstanceOf(HTTPError)
+    expect(err.problem).toBeDefined()
+    expect(err.problem?.type).toBe("https://example.test/errors/insufficient-funds")
+    expect(err.problem?.title).toBe("Insufficient Funds")
+    expect(err.problem?.status).toBe(402)
+    expect(err.problem?.detail).toBe("Your balance is $0.00.")
+    expect(err.problem?.instance).toBe("/transactions/123")
+    // Extension fields are preserved.
+    expect(err.problem?.balance).toBe(0)
+  })
+
+  it("includes problem.detail in the error message when present", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(
+          JSON.stringify({
+            title: "Validation Error",
+            detail: "field 'email' is required",
+          }),
+          {
+            status: 400,
+            statusText: "Bad Request",
+            headers: { "content-type": "application/problem+json" },
+          },
+        ),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const err = (await m.post("https://api.test/", { x: 1 }).catch((e) => e)) as HTTPError
+    expect(err.message).toContain("400")
+    expect(err.message).toContain("field 'email' is required")
+  })
+
+  it("falls back to problem.title when detail is missing", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(JSON.stringify({ title: "Forbidden" }), {
+          status: 403,
+          headers: { "content-type": "application/problem+json" },
+        }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const err = (await m.get("https://api.test/").catch((e) => e)) as HTTPError
+    expect(err.message).toContain("Forbidden")
+  })
+
+  it("non-problem content-type → err.problem is undefined", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(JSON.stringify({ title: "Forbidden" }), {
+          status: 403,
+          headers: { "content-type": "application/json" },
+        }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const err = (await m.get("https://api.test/").catch((e) => e)) as HTTPError
+    expect(err).toBeInstanceOf(HTTPError)
+    expect(err.problem).toBeUndefined()
+  })
+
+  it("application/problem+json with charset parameter still parses", async () => {
+    const driver = {
+      name: "p",
+      request: async () =>
+        new Response(JSON.stringify({ title: "x", detail: "y" }), {
+          status: 400,
+          headers: { "content-type": "application/problem+json; charset=utf-8" },
+        }),
+    }
+    const m = createMisina({ driver, retry: 0 })
+
+    const err = (await m.get("https://api.test/").catch((e) => e)) as HTTPError
+    expect(err.problem?.title).toBe("x")
+  })
+
+  it("ProblemDetails type re-exports from the root", () => {
+    // Compile-time check: the type is reachable from the root entry.
+    const sample: ProblemDetails = { title: "x", status: 400 }
+    expect(sample.title).toBe("x")
+  })
+})