@c9up/ream 0.1.25 → 0.1.27

package/src/testing/RequestBuilder.ts

@@ -1,19 +1,44 @@
-import type { TestResponse } from './TestClient.js'
-
 /**
- * Fluent HTTP request builder with assertion methods.
+ * Fluent HTTP request builder with assertion methods (`@japa/api-client` model).
  *
  *   await client
- *     .fluent('GET', '/api/users/42')
+ *     .get('/api/users/42')
  *     .withAuth(user)
- *     .expectStatus(200)
- *     .expectJson({ id: 42 })
+ *     .assertOk()
+ *     .assertBody({ id: 42 })
  *
- * The builder chains: setters return `this`, assertion methods send the
- * request on first call (memoised) and return a `Promise<this>` so further
- * assertions can be awaited or chained via `await`.
+ * The builder chains SYNCHRONOUSLY: setters and assertion methods both return
+ * `this`. Assertions are LAZY — each registers a check; the request is sent once
+ * and every check runs, in order, when the builder is awaited (it is thenable,
+ * so `await builder` resolves to the {@link ApiResponse}). A plain
+ * `await client.get('/x')` (no assertion) just sends and returns the response.
  */
 
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import type { Readable } from 'node:stream'
+import {
+  ApiResponse,
+  capBody,
+  ExpectationError,
+  partialMatch,
+  STATUS_ASSERTIONS,
+  type StatusAssertions,
+  type TestResponse,
+} from './ApiResponse.js'
+
+// Re-export the shared response types + matchers so `@c9up/ream/testing`
+// consumers keep importing them from here (back-compat).
+export {
+  ApiResponse,
+  deepEqual,
+  partialMatch,
+  type ResponseCookie,
+  type ResponseError,
+  type ResponseFile,
+  type TestResponse,
+} from './ApiResponse.js'
+
 export interface AuthSubject {
   /** String or numeric user id — used by `withAuth` / `asUser` to sign the session. */
   id: string | number
@@ -28,15 +53,52 @@ export interface AuthStrategy {
   cookiesFor?(subject: AuthSubject): Record<string, string> | Promise<Record<string, string>>
 }
 
-/** Assertion failure — plain Error so tests see a clean stack trace. */
-class ExpectationError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'ExpectationError'
-  }
+/**
+ * HTTP methods. The common verbs are named; `request(url, method)` also accepts
+ * any other method (e.g. `TRACE`, `CONNECT`) — Japa parity — via the wider
+ * string fallback.
+ */
+export type HttpMethod =
+  | 'GET'
+  | 'HEAD'
+  | 'POST'
+  | 'PUT'
+  | 'PATCH'
+  | 'DELETE'
+  | 'OPTIONS'
+  | 'TRACE'
+  | 'CONNECT'
+  | (string & {})
+
+/** Cookie the signed CSRF token is issued in (blackhole default: `XSRF-TOKEN`). */
+const CSRF_COOKIE_NAME = 'XSRF-TOKEN'
+/** Header the client echoes the token back in (Axios/Angular default). */
+const CSRF_HEADER_NAME = 'x-xsrf-token'
+
+/** Content-type / accept shorthands — mirrors japa/api-client's `.type()`/`.accept()`. */
+const TYPE_SHORTHANDS: Record<string, string> = {
+  json: 'application/json',
+  form: 'application/x-www-form-urlencoded',
+  urlencoded: 'application/x-www-form-urlencoded',
+  text: 'text/plain',
+  html: 'text/html',
+  xml: 'application/xml',
+}
+
+/** Expand a shorthand (`'json'`) to a full MIME type, or pass a full type through. */
+function resolveMime(type: string): string {
+  return TYPE_SHORTHANDS[type] ?? type
 }
 
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+/** Primitive accepted as a query-string value (mirrors `.qs()` in japa/api-client). */
+type QueryValue = string | number | boolean
+/** Query-string map — a value or an array of values (repeated key). */
+export type QueryParams = Record<string, QueryValue | ReadonlyArray<QueryValue>>
+
+/** A scalar accepted by `form()`/`fields()` — Japa parity (arrays repeat the key). */
+export type FieldValue = string | number | boolean | Buffer
+/** A value accepted by a multipart `field()`/`file()` — Japa parity (incl. streams/blobs). */
+export type MultipartValue = string | number | boolean | Buffer | Blob | Readable
 
 /**
  * Internal low-level sender — matches what the TestClient exposes.
@@ -48,22 +110,42 @@ export type HttpSender = (
   init: {
     headers: Record<string, string>
     body: Buffer
+    /** Per-request socket timeout (ms) — Japa `.timeout()`. Sender may honour it. */
+    timeoutMs?: number
   },
 ) => Promise<TestResponse>
 
 /** Options for a multipart file part — mirrors Adonis/japa's `.file()` options. */
 export interface FilePart {
-  /** Filename advertised in the part's `Content-Disposition`. Defaults to the field name. */
+  /** Filename advertised in the part's `Content-Disposition`. Defaults to the field name / basename. */
   filename?: string
   /** MIME type of the part. Defaults to `application/octet-stream`. */
   contentType?: string
 }
 
-/** One encoded multipart/form-data part — a text field or an uploaded file. */
+/**
+ * One multipart/form-data part — a field or an uploaded file. The value/content
+ * may be a stream/blob; it is resolved to a Buffer at send time (`#execute`).
+ */
 type MultipartPart =
-  | { kind: 'field'; name: string; value: string }
-  | { kind: 'file'; name: string; filename: string; contentType: string; content: Buffer }
-
+  | { kind: 'field'; name: string; value: MultipartValue }
+  | { kind: 'file'; name: string; filename: string; contentType: string; content: MultipartValue }
+
+/** HTTP statuses that trigger redirect-following (Japa `.redirects()`). */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+/** Japa follows 5 redirects by default. */
+const DEFAULT_MAX_REDIRECTS = 5
+
+/** Consumer-registered macros/getters (Japa `ApiRequest.macro`/`.getter`). */
+const requestMacros = new Map<string, unknown>()
+const requestGetters = new Map<string, (this: RequestBuilder, req: RequestBuilder) => unknown>()
+/** Consumer-registered request body serializers (Japa `ApiRequest.addSerializer`), by name. */
+const requestSerializers = new Map<
+  string,
+  (data: unknown) => { body: Buffer; contentType: string }
+>()
+
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached from STATUS_ASSERTIONS at load — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
 export class RequestBuilder {
   #sender: HttpSender
   #method: HttpMethod
@@ -72,9 +154,16 @@ export class RequestBuilder {
   #body: Buffer = Buffer.alloc(0)
   #multipart: MultipartPart[] = []
   #cookies: Record<string, string> = {}
+  #query = new URLSearchParams()
   #authStrategy: AuthStrategy | null
   #pendingAuth: AuthSubject | null = null
-  #sent: Promise<TestResponse> | null = null
+  #timeoutMs: number | undefined
+  #maxRedirects = DEFAULT_MAX_REDIRECTS
+  #sent: Promise<ApiResponse> | null = null
+  // Lazy assertions (japa model): each `assert*`/`expect*` registers a check and
+  // returns `this` synchronously; the checks run in order when the builder is
+  // awaited (`then`) — after the single send.
+  #checks: Array<(res: ApiResponse) => void> = []
 
   constructor(
     sender: HttpSender,
@@ -86,6 +175,7 @@ export class RequestBuilder {
     this.#method = method
     this.#path = path
     this.#authStrategy = authStrategy
+    applyRequestExtensions(this)
   }
 
   headers(map: Record<string, string>): this {
@@ -95,8 +185,9 @@ export class RequestBuilder {
     return this
   }
 
-  header(name: string, value: string): this {
-    this.#headers[name.toLowerCase()] = value
+  header(name: string, value: string | string[]): this {
+    // Japa accepts string | string[]; a list is joined into one header value.
+    this.#headers[name.toLowerCase()] = Array.isArray(value) ? value.join(', ') : value
     return this
   }
 
@@ -106,45 +197,80 @@ export class RequestBuilder {
     return this
   }
 
+  /** Japa `.unsafeJson()` — set a JSON body without any transform (alias of {@link json}). */
+  unsafeJson(data: unknown): this {
+    return this.json(data)
+  }
+
   body(data: Buffer | string, contentType?: string): this {
     this.#body = typeof data === 'string' ? Buffer.from(data, 'utf8') : data
     if (contentType) this.#headers['content-type'] = contentType
     return this
   }
 
-  form(data: Record<string, string>): this {
-    const pairs = Object.entries(data).map(
-      ([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`,
-    )
+  form(data: Record<string, FieldValue | FieldValue[]>): this {
+    // Array values repeat the key (`a=1&a=2`) — Japa parity.
+    const pairs: string[] = []
+    for (const [k, v] of Object.entries(data)) {
+      const values = Array.isArray(v) ? v : [v]
+      for (const item of values) {
+        pairs.push(`${encodeURIComponent(k)}=${encodeURIComponent(fieldToString(item))}`)
+      }
+    }
     this.#body = Buffer.from(pairs.join('&'), 'utf8')
     this.#headers['content-type'] = 'application/x-www-form-urlencoded'
     return this
   }
 
+  /** Japa `.unsafeForm()` — set a urlencoded body without transform (alias of {@link form}). */
+  unsafeForm(data: Record<string, FieldValue | FieldValue[]>): this {
+    return this.form(data)
+  }
+
   /**
-   * Add a `multipart/form-data` text field — mirrors Adonis/japa's `.field()`.
-   * Calling `.field()` or `.file()` switches the body to multipart (use
-   * `.form()` for `application/x-www-form-urlencoded`). The boundary +
-   * `Content-Type` header are produced at send time.
+   * Add a `multipart/form-data` field — mirrors Adonis/japa's `.field()`. Accepts
+   * a string/number/boolean, a Buffer, a Blob, a Readable stream, or an array of
+   * these (repeated part). Calling `.field()`/`.fields()`/`.file()` switches the
+   * body to multipart; the boundary + `Content-Type` header are produced at send
+   * time (streams/blobs are drained to Buffers then).
    */
-  field(name: string, value: string): this {
-    this.#multipart.push({ kind: 'field', name, value })
+  field(name: string, value: MultipartValue | MultipartValue[]): this {
+    const values = Array.isArray(value) ? value : [value]
+    for (const v of values) {
+      this.#multipart.push({
+        kind: 'field',
+        name,
+        value: isScalar(v) ? fieldToString(v) : v,
+      })
+    }
+    return this
+  }
+
+  /** Add several multipart fields at once — Japa `.fields()`. */
+  fields(map: Record<string, MultipartValue | MultipartValue[]>): this {
+    for (const [name, value] of Object.entries(map)) {
+      this.field(name, value)
+    }
     return this
   }
 
   /**
    * Attach a file as a `multipart/form-data` part — mirrors Adonis/japa's
-   * `.file(field, contents, { filename, contentType })`. `contents` is a
-   * Buffer (binary) or a string (encoded as utf8). Server-side
-   * `request.file(field, …)` reads the resulting part.
+   * `.file(field, value, { filename, contentType })`. `value` is a Buffer, a
+   * Blob, a Readable stream, OR a string absolute PATH to a file on disk (read at
+   * call time, Japa parity). The filename defaults to the path basename / field
+   * name; streams/blobs are drained to Buffers at send time.
    */
-  file(field: string, contents: Buffer | string, options: FilePart = {}): this {
+  file(field: string, value: Buffer | string | Blob | Readable, options: FilePart = {}): this {
+    // A string is a PATH → read now; other kinds are resolved at send time.
+    const content: MultipartValue = typeof value === 'string' ? readFileSync(value) : value
+    const filename = options.filename ?? (typeof value === 'string' ? basename(value) : field)
     this.#multipart.push({
       kind: 'file',
       name: field,
-      filename: options.filename ?? field,
+      filename,
       contentType: options.contentType ?? 'application/octet-stream',
-      content: typeof contents === 'string' ? Buffer.from(contents, 'utf8') : contents,
+      content,
     })
     return this
   }
@@ -159,10 +285,130 @@ export class RequestBuilder {
     return this
   }
 
+  /**
+   * Append query-string params — mirrors japa/api-client's `.qs()`. Values are
+   * URL-encoded; arrays repeat the key (`?tag=a&tag=b`). Merges with any query
+   * string already on the path and with earlier `.qs()` calls.
+   */
+  qs(params: QueryParams): this {
+    for (const [key, value] of Object.entries(params)) {
+      if (Array.isArray(value)) {
+        for (const item of value) this.#query.append(key, String(item))
+      } else {
+        this.#query.append(key, String(value))
+      }
+    }
+    return this
+  }
+
+  /**
+   * Append query params WITHOUT any validation/normalisation — Japa
+   * `.unsafeQs({ … })`. Values are still URL-encoded so the wire stays valid, but
+   * (unlike `.qs()`) no key filtering is applied; arrays repeat the key.
+   */
+  unsafeQs(params: QueryParams): this {
+    return this.qs(params)
+  }
+
+  /** Pass a bearer token as the `Authorization` header — japa `.bearerToken()`. */
+  bearerToken(token: string): this {
+    this.#headers.authorization = `Bearer ${token}`
+    return this
+  }
+
+  /** Pass HTTP Basic credentials as the `Authorization` header — japa `.basicAuth()`. */
+  basicAuth(user: string, password: string): this {
+    const encoded = Buffer.from(`${user}:${password}`, 'utf8').toString('base64')
+    this.#headers.authorization = `Basic ${encoded}`
+    return this
+  }
+
+  /**
+   * Set the request `Content-Type` from a shorthand (`'json'`, `'form'`, …) or a
+   * full MIME type — mirrors japa/api-client's `.type()`.
+   */
+  type(mime: string): this {
+    this.#headers['content-type'] = resolveMime(mime)
+    return this
+  }
+
+  /**
+   * Set the `Accept` header from a shorthand (`'json'`, `'html'`, …) or a full
+   * MIME type — mirrors japa/api-client's `.accept()`.
+   */
+  accept(mime: string): this {
+    this.#headers.accept = resolveMime(mime)
+    return this
+  }
+
+  /** Per-request timeout in ms — Japa `.timeout()`. Honoured by the sender. */
+  timeout(ms: number): this {
+    this.#timeoutMs = ms
+    return this
+  }
+
+  /**
+   * Follow up to `count` redirects before resolving — Japa `.redirects()`.
+   * Defaults to 5 (Japa default); pass `0` to disable following.
+   */
+  redirects(count: number): this {
+    this.#maxRedirects = Math.max(0, count)
+    return this
+  }
+
+  // TLS knobs — Japa parity. The test server is plain HTTP over loopback, so
+  // these are inert (there is no TLS handshake to configure); they exist so
+  // Japa-shaped code type-checks and runs unchanged. NAMED as a ream deviation.
+  /** No-op: the loopback test server has no TLS — Japa `.trustLocalhost()`. */
+  trustLocalhost(_trust = true): this {
+    return this
+  }
+  /** No-op: no TLS on the loopback test server — Japa `.ca()`. */
+  ca(_cert: string): this {
+    return this
+  }
+  /** No-op: no TLS on the loopback test server — Japa `.cert()`. */
+  cert(_chain: string): this {
+    return this
+  }
+  /** No-op: no TLS on the loopback test server — Japa `.privateKey()`. */
+  privateKey(_key: string): this {
+    return this
+  }
+  /** No-op: no TLS on the loopback test server — Japa `.pfx()`. */
+  pfx(_encoded: string | Buffer): this {
+    return this
+  }
+  /** No-op: no TLS on the loopback test server — Japa `.disableTLSCerts()`. */
+  disableTLSCerts(): this {
+    return this
+  }
+
+  /**
+   * Satisfy blackhole's signed double-submit CSRF check: echo the `XSRF-TOKEN`
+   * cookie back in the `X-XSRF-TOKEN` header (the pair the server compares).
+   */
+  withCsrf(token?: string): this {
+    if (token !== undefined) this.#cookies[CSRF_COOKIE_NAME] = token
+    const value = this.#cookies[CSRF_COOKIE_NAME]
+    if (value === undefined) {
+      throw new Error(
+        `RequestBuilder: withCsrf() found no '${CSRF_COOKIE_NAME}' cookie. Set it first via ` +
+          `.cookie('${CSRF_COOKIE_NAME}', token) (extracted from a prior safe GET) or pass the token: withCsrf(token).`,
+      )
+    }
+    this.#headers[CSRF_HEADER_NAME] = value
+    return this
+  }
+
+  /** japa/api-client's spelling of {@link withCsrf}. */
+  withCsrfToken(token?: string): this {
+    return this.withCsrf(token)
+  }
+
   /**
    * Attach auth for a user. Uses the strategy passed to `client`'s `auth`
-   * option — Warden's session/JWT/API-key strategy decides the header/cookie
-   * shape. Without a strategy, throws at send time.
+   * option. Without a strategy, throws at send time.
    */
   withAuth(subject: AuthSubject): this {
     this.#pendingAuth = subject
@@ -175,82 +421,123 @@ export class RequestBuilder {
     return this
   }
 
-  /** Fire the request (once) and return the raw response. Idempotent. */
-  send(): Promise<TestResponse> {
+  /** Fire the request (once) and return the rich response. Idempotent. */
+  send(): Promise<ApiResponse> {
     if (this.#sent === null) this.#sent = this.#execute()
     return this.#sent
   }
 
-  async expectStatus(code: number): Promise<this> {
-    const res = await this.send()
-    if (res.status !== code) {
-      throw new ExpectationError(
-        `Expected status ${code}, got ${res.status}. Body: ${capBody(res.body)}`,
-      )
-    }
-    return this
+  /**
+   * Thenable — `await client.get('/x')` sends the request and resolves to the
+   * {@link ApiResponse} (Japa/api-client parity). Assertion methods return `this`;
+   * awaiting one resolves via this `then` to the response after running the checks.
+   */
+  // biome-ignore lint/suspicious/noThenProperty: the thenable IS the public API — `await client.get('/x')` is the documented Japa/api-client ergonomic; removing `.then` breaks every await-the-builder call site.
+  then<R1 = ApiResponse, R2 = never>(
+    onFulfilled?: ((value: ApiResponse) => R1 | PromiseLike<R1>) | null,
+    onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): Promise<R1 | R2> {
+    return this.#settle().then(onFulfilled, onRejected)
   }
 
-  async expectHeader(name: string, value: string | RegExp): Promise<this> {
+  /** Send once, then run every registered assertion (throws on first failure). */
+  async #settle(): Promise<ApiResponse> {
     const res = await this.send()
-    const actual = res.headers[name.toLowerCase()]
-    if (actual === undefined) {
-      throw new ExpectationError(
-        `Expected header ${name}, not present in response headers: ${Object.keys(res.headers).join(', ')}`,
-      )
-    }
-    if (value instanceof RegExp) {
-      if (!value.test(actual)) {
-        throw new ExpectationError(`Expected header ${name} to match ${value}, got "${actual}"`)
-      }
-    } else if (actual !== value) {
-      throw new ExpectationError(`Expected header ${name} = "${value}", got "${actual}"`)
-    }
+    for (const check of this.#checks) check(res)
+    return res
+  }
+
+  /** Register a lazy assertion; returns `this` for synchronous chaining. */
+  #assert(check: (res: ApiResponse) => void): this {
+    this.#checks.push(check)
     return this
   }
 
-  async expectCookie(name: string, value?: string | RegExp): Promise<this> {
-    const res = await this.send()
-    const setCookie = res.headers['set-cookie']
-    if (!setCookie) {
-      throw new ExpectationError(`Expected cookie ${name}, but no Set-Cookie header was returned`)
-    }
-    const cookies = setCookie.split(/,(?=\s*\w+=)/)
-    const match = cookies.find((c) => c.trimStart().startsWith(`${name}=`))
-    if (!match) {
-      throw new ExpectationError(`Expected cookie ${name}, not found in: ${setCookie}`)
-    }
-    if (value === undefined) return this
-    const rawVal = match.split(';')[0]?.split('=')[1] ?? ''
-    if (value instanceof RegExp) {
-      if (!value.test(rawVal)) {
-        throw new ExpectationError(`Expected cookie ${name} to match ${value}, got "${rawVal}"`)
+  // ── ream-flavoured `expect*` aliases (kept for back-compat) ───────────────
+
+  expectStatus(code: number): this {
+    return this.#assert((res) => res.assertStatus(code))
+  }
+  expectHeader(name: string, value: string | RegExp): this {
+    return this.#assert((res) => res.assertHeader(name, value))
+  }
+  expectCookie(name: string, value?: string | RegExp): this {
+    return this.#assert((res) => res.assertCookie(name, value))
+  }
+  expectJson(expected: unknown): this {
+    // ream alias: partial JSON match with its own message (kept for back-compat;
+    // `assertBodyContains` is the Japa-named equivalent).
+    return this.#assert((res) => {
+      if (!partialMatch(res.json(), expected)) {
+        throw new ExpectationError(
+          `JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(res.json()))}`,
+        )
       }
-    } else if (rawVal !== value) {
-      throw new ExpectationError(`Expected cookie ${name} = "${value}", got "${rawVal}"`)
-    }
-    return this
+    })
   }
 
-  async expectJson(expected: unknown): Promise<this> {
-    const res = await this.send()
-    let actual: unknown
-    try {
-      actual = res.json()
-    } catch (err) {
-      throw new ExpectationError(
-        `Expected JSON body, got non-JSON. Body: ${capBody(res.body)} (parse error: ${err instanceof Error ? err.message : String(err)})`,
-      )
-    }
-    if (!partialMatch(actual, expected)) {
-      throw new ExpectationError(
-        `JSON partial match failed.\nExpected (partial): ${JSON.stringify(expected)}\nActual: ${capBody(JSON.stringify(actual))}`,
-      )
-    }
+  // ── Japa assertions (lazy — delegate to the response) ─────────────────────
+
+  assertStatus(code: number): this {
+    return this.#assert((res) => res.assertStatus(code))
+  }
+  assertHeader(name: string, value?: string | RegExp): this {
+    return this.#assert((res) => res.assertHeader(name, value))
+  }
+  assertHeaderMissing(name: string): this {
+    return this.#assert((res) => res.assertHeaderMissing(name))
+  }
+  assertCookie(name: string, value?: string | RegExp): this {
+    return this.#assert((res) => res.assertCookie(name, value))
+  }
+  assertCookieMissing(name: string): this {
+    return this.#assert((res) => res.assertCookieMissing(name))
+  }
+  assertBody(expected: unknown): this {
+    return this.#assert((res) => res.assertBody(expected))
+  }
+  assertBodyContains(subset: unknown): this {
+    return this.#assert((res) => res.assertBodyContains(subset))
+  }
+  assertBodyNotContains(subset: unknown): this {
+    return this.#assert((res) => res.assertBodyNotContains(subset))
+  }
+  assertTextIncludes(substring: string): this {
+    return this.#assert((res) => res.assertTextIncludes(substring))
+  }
+  assertRedirectsTo(path: string): this {
+    return this.#assert((res) => res.assertRedirectsTo(path))
+  }
+
+  // ── Request debugging (Japa `request.dump*` — dumps the REQUEST) ──────────
+
+  /** Print the pending request (method/path/headers/body) — Japa `request.dump()`. */
+  dump(): this {
+    process.stderr.write(
+      `[helix:request.dump] ${this.#method} ${this.#path}\n` +
+        `headers: ${JSON.stringify(this.#headers, null, 2)}\n` +
+        `cookies: ${JSON.stringify(this.#cookies, null, 2)}\n` +
+        `body: ${capBody(this.#body.toString('utf8'), 2048)}\n`,
+    )
+    return this
+  }
+  /** Print only the pending request body — Japa `request.dumpBody()`. */
+  dumpBody(): this {
+    process.stderr.write(`[helix:request.dumpBody] ${capBody(this.#body.toString('utf8'), 2048)}\n`)
+    return this
+  }
+  /** Print only the pending request headers — Japa `request.dumpHeaders()`. */
+  dumpHeaders(): this {
+    process.stderr.write(`[helix:request.dumpHeaders] ${JSON.stringify(this.#headers, null, 2)}\n`)
+    return this
+  }
+  /** Print only the pending request cookies — Japa `request.dumpCookies()`. */
+  dumpCookies(): this {
+    process.stderr.write(`[helix:request.dumpCookies] ${JSON.stringify(this.#cookies, null, 2)}\n`)
     return this
   }
 
-  async #execute(): Promise<TestResponse> {
+  async #execute(): Promise<ApiResponse> {
     // Resolve auth before sending.
     if (this.#pendingAuth !== null) {
       if (!this.#authStrategy) {
@@ -277,7 +564,21 @@ export class RequestBuilder {
     // json()/form()/body(); encode them with a fresh boundary at send time.
     if (this.#multipart.length > 0) {
       const boundary = `----ReamRequestBuilder${crypto.randomUUID().replace(/-/g, '')}`
-      this.#body = encodeMultipart(this.#multipart, boundary)
+      // Drain any stream/blob part to a Buffer before encoding (Japa parity).
+      const resolved: ResolvedPart[] = await Promise.all(
+        this.#multipart.map(async (p) =>
+          p.kind === 'field'
+            ? { kind: 'field' as const, name: p.name, value: await toBuffer(p.value) }
+            : {
+                kind: 'file' as const,
+                name: p.name,
+                filename: p.filename,
+                contentType: p.contentType,
+                content: await toBuffer(p.content),
+              },
+        ),
+      )
+      this.#body = encodeMultipart(resolved, boundary)
       this.#headers['content-type'] = `multipart/form-data; boundary=${boundary}`
     }
 
@@ -287,15 +588,178 @@ export class RequestBuilder {
       this.#headers.cookie = cookieEntries.map(([k, v]) => `${k}=${v}`).join('; ')
     }
 
-    return this.#sender(this.#method, this.#path, {
+    // Merge `.qs()` params into the path, preserving any existing query string.
+    let path = this.#path
+    const qs = this.#query.toString()
+    if (qs) {
+      path += (path.includes('?') ? '&' : '?') + qs
+    }
+
+    let method = this.#method
+    let body = this.#body
+    let raw = await this.#sender(method, path, {
       headers: this.#headers,
-      body: this.#body,
+      body,
+      timeoutMs: this.#timeoutMs,
     })
+
+    // Follow redirects up to the configured budget — Japa `.redirects()` (5 by default).
+    const chain: string[] = []
+    let followed = 0
+    while (
+      followed < this.#maxRedirects &&
+      REDIRECT_STATUSES.has(raw.status) &&
+      raw.headers.location !== undefined
+    ) {
+      const location = raw.headers.location
+      chain.push(location)
+      followed += 1
+      path = location.startsWith('http')
+        ? new URL(location).pathname + new URL(location).search
+        : location
+      // 303 (and, per browser convention, 301/302) switch to GET with no body;
+      // 307/308 preserve the method and body.
+      if (raw.status === 307 || raw.status === 308) {
+        // keep method + body
+      } else {
+        method = 'GET'
+        body = Buffer.alloc(0)
+        delete this.#headers['content-type']
+      }
+      raw = await this.#sender(method, path, {
+        headers: this.#headers,
+        body,
+        timeoutMs: this.#timeoutMs,
+      })
+    }
+
+    return new ApiResponse(raw, { method, redirects: chain })
+  }
+
+  /**
+   * Serialize `data` with a registered serializer and set it as the request body
+   * — the send-side twin of {@link ApiResponse.addParser}. Register serializers
+   * via {@link RequestBuilder.addSerializer} (Japa `ApiRequest.addSerializer`).
+   */
+  serialize(name: string, data: unknown): this {
+    const serializer = requestSerializers.get(name)
+    if (!serializer) {
+      throw new Error(
+        `RequestBuilder: no serializer registered for "${name}" (see RequestBuilder.addSerializer).`,
+      )
+    }
+    const { body, contentType } = serializer(data)
+    this.#body = body
+    this.#headers['content-type'] = contentType
+    return this
+  }
+
+  /**
+   * Register a shared property (Japa `ApiRequest.macro`) or lazy getter
+   * (`ApiRequest.getter`). The callback is invoked with `this` bound to the
+   * builder AND the builder as its first arg, so both Japa's
+   * `function () { return this.header('x') }` and `(req) => …` work.
+   */
+  static macro(name: string, value: unknown): void {
+    requestMacros.set(name, value)
+  }
+  static getter(name: string, fn: (this: RequestBuilder, req: RequestBuilder) => unknown): void {
+    requestGetters.set(name, fn)
+  }
+
+  /** Register a request body serializer — Japa `ApiRequest.addSerializer`. */
+  static addSerializer(
+    name: string,
+    fn: (data: unknown) => { body: Buffer; contentType: string },
+  ): void {
+    requestSerializers.set(name, fn)
+  }
+
+  /** Register a response body parser — Japa `ApiRequest.addParser` (delegates to ApiResponse). */
+  static addParser(
+    contentType: string,
+    fn: (body: string, headers: Record<string, string>) => unknown,
+  ): void {
+    ApiResponse.addParser(contentType, fn)
   }
 }
 
-function capBody(s: string, max = 512): string {
-  return s.length <= max ? s : `${s.slice(0, max)}...[truncated]`
+/** The status-shortcut assertions (lazy) are typed onto the builder. */
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: the merged interface (StatusAssertions) types the status-shortcut asserts attached from STATUS_ASSERTIONS at load — the same generated-method pattern as EonSchema/Macroable (AdonisJS parity); every member is implemented, so the merge is safe.
+export interface RequestBuilder extends StatusAssertions<RequestBuilder> {}
+
+// Attach the lazy status-shortcut assertions from the shared map so the builder
+// and ApiResponse never disagree on the code set. Each defers to the public
+// `expectStatus` (private fields aren't reachable from prototype-added fns).
+for (const [method, code] of Object.entries(STATUS_ASSERTIONS)) {
+  Object.defineProperty(RequestBuilder.prototype, method, {
+    value(this: RequestBuilder) {
+      return this.expectStatus(code)
+    },
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  })
+}
+
+/** Coerce a field value to its wire string (Buffers are handled separately). */
+function fieldToString(value: FieldValue): string {
+  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value)
+}
+
+/** Whether a multipart value is a scalar (string/number/boolean/Buffer), not a stream/blob. */
+function isScalar(v: MultipartValue): v is FieldValue {
+  return (
+    typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || Buffer.isBuffer(v)
+  )
+}
+
+/** Drain a multipart value (string/Buffer/Blob/Readable) to a Buffer at send time. */
+async function toBuffer(v: MultipartValue): Promise<Buffer> {
+  if (Buffer.isBuffer(v)) return v
+  if (typeof v === 'string') return Buffer.from(v, 'utf8')
+  if (typeof v === 'number' || typeof v === 'boolean') return Buffer.from(String(v), 'utf8')
+  // `in` narrows the Blob | Readable union without a cast: only Blob has arrayBuffer.
+  if ('arrayBuffer' in v) return Buffer.from(await v.arrayBuffer())
+  // Readable / async-iterable → collect chunks.
+  const chunks: Buffer[] = []
+  for await (const chunk of v) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+  }
+  return Buffer.concat(chunks)
+}
+
+/** A multipart part whose value/content has been resolved to a Buffer (send time). */
+type ResolvedPart =
+  | { kind: 'field'; name: string; value: Buffer }
+  | { kind: 'file'; name: string; filename: string; contentType: string; content: Buffer }
+
+/** Apply registered request macros/getters onto a freshly built builder. */
+function applyRequestExtensions(req: RequestBuilder): void {
+  for (const [name, value] of requestMacros) {
+    Object.defineProperty(req, name, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  for (const [name, fn] of requestGetters) {
+    let computed = false
+    let cached: unknown
+    Object.defineProperty(req, name, {
+      enumerable: true,
+      configurable: true,
+      get() {
+        if (!computed) {
+          // `this`-bound AND passed as arg → both `function(){this.x}` and `(req)=>req.x` work.
+          cached = fn.call(req, req)
+          computed = true
+        }
+        return cached
+      },
+    })
+  }
 }
 
 /** Strip CR/LF and escape quotes so a name/filename can't break the headers. */
@@ -303,19 +767,21 @@ function sanitizeHeaderParam(value: string): string {
   return value.replace(/[\r\n]/g, '').replace(/"/g, '%22')
 }
 
-/** Encode multipart/form-data parts (RFC 7578) into a single body Buffer. */
-function encodeMultipart(parts: MultipartPart[], boundary: string): Buffer {
+/** Encode resolved multipart/form-data parts (RFC 7578) into a single body Buffer. */
+function encodeMultipart(parts: ResolvedPart[], boundary: string): Buffer {
   const CRLF = '\r\n'
   const chunks: Buffer[] = []
   for (const part of parts) {
     if (part.kind === 'field') {
+      const valueBuf = part.value
       chunks.push(
         Buffer.from(
           `--${boundary}${CRLF}` +
-            `Content-Disposition: form-data; name="${sanitizeHeaderParam(part.name)}"${CRLF}${CRLF}` +
-            `${part.value}${CRLF}`,
+            `Content-Disposition: form-data; name="${sanitizeHeaderParam(part.name)}"${CRLF}${CRLF}`,
           'utf8',
         ),
+        valueBuf,
+        Buffer.from(CRLF, 'utf8'),
       )
     } else {
       chunks.push(
@@ -333,29 +799,3 @@ function encodeMultipart(parts: MultipartPart[], boundary: string): Buffer {
   chunks.push(Buffer.from(`--${boundary}--${CRLF}`, 'utf8'))
   return Buffer.concat(chunks)
 }
-
-/** Narrowing guard — a non-null, non-array object usable as a string map. */
-function isRecord(x: unknown): x is Record<string, unknown> {
-  return typeof x === 'object' && x !== null && !Array.isArray(x)
-}
-
-/**
- * Partial deep-match. For objects, every key in `expected` must match in
- * `actual`. For arrays, every element in `expected` must match SOMEWHERE in
- * `actual` (order-independent). Primitives compared by strict equality.
- */
-export function partialMatch(actual: unknown, expected: unknown): boolean {
-  if (expected === null || expected === undefined) {
-    return actual === expected
-  }
-  if (typeof expected !== 'object') return actual === expected
-  if (Array.isArray(expected)) {
-    if (!Array.isArray(actual)) return false
-    return expected.every((want) => actual.some((have) => partialMatch(have, want)))
-  }
-  if (!isRecord(actual) || !isRecord(expected)) return false
-  for (const key of Object.keys(expected)) {
-    if (!partialMatch(actual[key], expected[key])) return false
-  }
-  return true
-}